diff options
Diffstat (limited to 'macros/texinfo/texinfo/doc')
58 files changed, 51616 insertions, 0 deletions
diff --git a/macros/texinfo/texinfo/doc/Makefile.am b/macros/texinfo/texinfo/doc/Makefile.am new file mode 100644 index 0000000000..e890e7bcbb --- /dev/null +++ b/macros/texinfo/texinfo/doc/Makefile.am @@ -0,0 +1,120 @@ +# Makefile.am for texinfo/doc. +# +# Copyright 2002-2019 Free Software Foundation, Inc. +# +# This file is free software; as a special exception the author gives +# unlimited permission to copy and/or distribute it, with or without +# modifications, as long as this notice is preserved. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the +# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +SUBDIRS = tp_api + +info_TEXINFOS = texinfo.texi info-stnd.texi +DISTCLEANFILES = texinfo.info* info-stnd.info* + +MAKEINFO_ENVIRONMENT = TEXINFO_DEV_SOURCE=1 ; export TEXINFO_DEV_SOURCE ; \ + top_srcdir="$(top_srcdir)" ; export top_srcdir ; \ + top_builddir="$(top_builddir)" ; export top_builddir ; +MAKEINFO = $(MAKEINFO_ENVIRONMENT) $(PERL) $(top_builddir)/tp/texi2any + +# We'd also like to use something like this, but Automake calls +# "install-info" directly. +# INSTALL_INFO = $(top_builddir)/$(native_tools)/util/ginstall-info + +TXI_XLATE = txi-ca.tex txi-cs.tex txi-de.tex txi-en.tex txi-es.tex \ + txi-fr.tex txi-hu.tex txi-is.tex txi-it.tex txi-ja.tex \ + txi-nb.tex txi-nl.tex txi-nn.tex txi-pl.tex txi-pt.tex \ + txi-ru.tex txi-sr.tex txi-tr.tex txi-uk.tex + +refcard_files = refcard/Makefile refcard/txicmdcheck \ + refcard/txirefcard-a4.pdf refcard/txirefcard.pdf \ + refcard/txirefcard.tex + +# Include our texinfo.tex, not Automake's. +EXTRA_DIST = epsf.tex texinfo.tex \ + fdl.texi \ + $(man_MANS) $(TXI_XLATE) \ + $(refcard_files) \ + texinfo-tex-test.texi texinfo-tex-test.WIDOWs \ + texinfo-ja.tex short-sample-ja.texi + +if INSTALL_WARNINGS +install-data-local: + @echo + @echo "WARNING: If your texmf tree does not already contain" + @echo " up-to-date versions, you must install" + @echo " texinfo.tex and txi-??.tex manually," + @echo " perhaps in TEXMF/tex/texinfo/," + @echo " where TEXMF is a root of your TeX tree." + @echo " See doc/README for some considerations." + @echo " You can run make TEXMF=/your/texmf install-tex to do this." + @echo + @echo " You may also need to install epsf.tex in" + @echo " TEXMF/tex/generic/dvips, if your TeX" + @echo " installation did not include it." +endif + +texmf_texinfo = $(TEXMF)/tex/texinfo +texmf_dvips = $(TEXMF)/tex/generic/epsf +install-tex: + test -n "$(TEXMF)" || (echo "TEXMF must be set." >&2; exit 1) + $(mkinstalldirs) $(DESTDIR)$(texmf_texinfo) $(DESTDIR)$(texmf_dvips) + $(INSTALL_DATA) $(srcdir)/texinfo.tex $(DESTDIR)$(texmf_texinfo)/texinfo.tex + $(INSTALL_DATA) $(srcdir)/epsf.tex $(DESTDIR)$(texmf_dvips)/epsf.tex + for f in $(TXI_XLATE); do \ + $(INSTALL_DATA) $(srcdir)/$$f $(DESTDIR)$(texmf_texinfo)/$$f; done + +# Do not create info files for distribution. +dist-info: + +# Rules for updating the online web pages for the documentation +# using the gendocs.sh script; see +# http://www.gnu.org/prep/maintain/html_node/Invoking-gendocs_002esh.html +# +# Invoke gendocs.sh from a gnulib checkout (outside our tree). +# +gnulib = $(abs_top_srcdir)/../gnulib +gendocs = $(gnulib)/build-aux/gendocs.sh +gendocs_templates = $(gnulib)/doc +gendocs_envvars = GENDOCS_TEMPLATE_DIR=$(gendocs_templates) +# +gendocs_email = bug-texinfo@gnu.org +gendocs_dir_url = /manual/ +gendocs_invoke = env $(gendocs_envvars) $(gendocs) --email $(gendocs_email) \ + --html '-c TOP_NODE_UP_URL=$(gendocs_dir_url)' +# A nice side effect of using --html is to eliminate the fancy css default; +# otherwise, we could use gendocs_template_min. +# +manual1 = info-stnd +manual1_title = "GNU standalone info manual" +# +manual2 = texinfo +manual2_title = "GNU Texinfo manual" +# +# We also make a little HTML document for pod2texi script. +pod2texi_pl = $(abs_top_srcdir)/Pod-Simple-Texinfo/pod2texi.pl + +# destination directory. +doctemp = wwwtemp +www_target = $(HOME)/gnu/www/texinfo/manual +# +wwwdoc-build: + rm -rf $(doctemp) && mkdir $(doctemp) + cd $(doctemp) \ + && ln -s ../*.texi . \ + && $(gendocs_invoke) -o $(manual1) $(manual1) $(manual1_title) \ + && $(gendocs_invoke) -o $(manual2) $(manual2) $(manual2_title) \ + && pod2html $(pod2texi_pl) >pod2texi.html \ + && echo "Manuals ready for web distribution under: $(doctemp)/" +# +# At official release, we need to update: +# http://www.gnu.org/software/texinfo/manual/ +wwwdoc-install: + cp -arf $(doctemp)/$(manual1) $(doctemp)/$(manual2) \ + $(doctemp)/pod2texi.html \ + $(www_target) + ls -ltu $(www_target)/*/html_node | tail # cvs rm -f obsolete files +# followed by cvs add of new files and cvs commit. diff --git a/macros/texinfo/texinfo/doc/Makefile.in b/macros/texinfo/texinfo/doc/Makefile.in new file mode 100644 index 0000000000..e944850a2f --- /dev/null +++ b/macros/texinfo/texinfo/doc/Makefile.in @@ -0,0 +1,1871 @@ +# Makefile.in generated by automake 1.16 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2018 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# Makefile.am for texinfo/doc. +# +# Copyright 2002-2019 Free Software Foundation, Inc. +# +# This file is free software; as a special exception the author gives +# unlimited permission to copy and/or distribute it, with or without +# modifications, as long as this notice is preserved. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the +# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +VPATH = @srcdir@ +am__is_gnu_make = { \ + if test -z '$(MAKELEVEL)'; then \ + false; \ + elif test -n '$(MAKE_HOST)'; then \ + true; \ + elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ + true; \ + else \ + false; \ + fi; \ +} +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/gnulib/m4/00gnulib.m4 \ + $(top_srcdir)/gnulib/m4/__inline.m4 \ + $(top_srcdir)/gnulib/m4/absolute-header.m4 \ + $(top_srcdir)/gnulib/m4/alloca.m4 \ + $(top_srcdir)/gnulib/m4/argz.m4 \ + $(top_srcdir)/gnulib/m4/btowc.m4 \ + $(top_srcdir)/gnulib/m4/builtin-expect.m4 \ + $(top_srcdir)/gnulib/m4/codeset.m4 \ + $(top_srcdir)/gnulib/m4/dirname.m4 \ + $(top_srcdir)/gnulib/m4/double-slash-root.m4 \ + $(top_srcdir)/gnulib/m4/eealloc.m4 \ + $(top_srcdir)/gnulib/m4/errno_h.m4 \ + $(top_srcdir)/gnulib/m4/error.m4 \ + $(top_srcdir)/gnulib/m4/exponentd.m4 \ + $(top_srcdir)/gnulib/m4/extensions.m4 \ + $(top_srcdir)/gnulib/m4/extern-inline.m4 \ + $(top_srcdir)/gnulib/m4/float_h.m4 \ + $(top_srcdir)/gnulib/m4/getopt.m4 \ + $(top_srcdir)/gnulib/m4/getprogname.m4 \ + $(top_srcdir)/gnulib/m4/gettext.m4 \ + $(top_srcdir)/gnulib/m4/glibc21.m4 \ + $(top_srcdir)/gnulib/m4/gnulib-common.m4 \ + $(top_srcdir)/gnulib/m4/gnulib-comp.m4 \ + $(top_srcdir)/gnulib/m4/host-cpu-c-abi.m4 \ + $(top_srcdir)/gnulib/m4/iconv.m4 \ + $(top_srcdir)/gnulib/m4/include_next.m4 \ + $(top_srcdir)/gnulib/m4/intlmacosx.m4 \ + $(top_srcdir)/gnulib/m4/intmax_t.m4 \ + $(top_srcdir)/gnulib/m4/inttypes_h.m4 \ + $(top_srcdir)/gnulib/m4/iswblank.m4 \ + $(top_srcdir)/gnulib/m4/langinfo_h.m4 \ + $(top_srcdir)/gnulib/m4/lib-ld.m4 \ + $(top_srcdir)/gnulib/m4/lib-link.m4 \ + $(top_srcdir)/gnulib/m4/lib-prefix.m4 \ + $(top_srcdir)/gnulib/m4/libunistring-base.m4 \ + $(top_srcdir)/gnulib/m4/limits-h.m4 \ + $(top_srcdir)/gnulib/m4/localcharset.m4 \ + $(top_srcdir)/gnulib/m4/locale-fr.m4 \ + $(top_srcdir)/gnulib/m4/locale-ja.m4 \ + $(top_srcdir)/gnulib/m4/locale-zh.m4 \ + $(top_srcdir)/gnulib/m4/locale_h.m4 \ + $(top_srcdir)/gnulib/m4/localeconv.m4 \ + $(top_srcdir)/gnulib/m4/lock.m4 \ + $(top_srcdir)/gnulib/m4/longlong.m4 \ + $(top_srcdir)/gnulib/m4/malloc.m4 \ + $(top_srcdir)/gnulib/m4/malloca.m4 \ + $(top_srcdir)/gnulib/m4/mbchar.m4 \ + $(top_srcdir)/gnulib/m4/mbiter.m4 \ + $(top_srcdir)/gnulib/m4/mbrtowc.m4 \ + $(top_srcdir)/gnulib/m4/mbsinit.m4 \ + $(top_srcdir)/gnulib/m4/mbslen.m4 \ + $(top_srcdir)/gnulib/m4/mbstate_t.m4 \ + $(top_srcdir)/gnulib/m4/mbswidth.m4 \ + $(top_srcdir)/gnulib/m4/mbtowc.m4 \ + $(top_srcdir)/gnulib/m4/memchr.m4 \ + $(top_srcdir)/gnulib/m4/mempcpy.m4 \ + $(top_srcdir)/gnulib/m4/memrchr.m4 \ + $(top_srcdir)/gnulib/m4/mmap-anon.m4 \ + $(top_srcdir)/gnulib/m4/msvc-inval.m4 \ + $(top_srcdir)/gnulib/m4/msvc-nothrow.m4 \ + $(top_srcdir)/gnulib/m4/multiarch.m4 \ + $(top_srcdir)/gnulib/m4/nl_langinfo.m4 \ + $(top_srcdir)/gnulib/m4/nls.m4 \ + $(top_srcdir)/gnulib/m4/nocrash.m4 \ + $(top_srcdir)/gnulib/m4/off_t.m4 $(top_srcdir)/gnulib/m4/po.m4 \ + $(top_srcdir)/gnulib/m4/printf.m4 \ + $(top_srcdir)/gnulib/m4/progtest.m4 \ + $(top_srcdir)/gnulib/m4/pthread_rwlock_rdlock.m4 \ + $(top_srcdir)/gnulib/m4/regex.m4 \ + $(top_srcdir)/gnulib/m4/size_max.m4 \ + $(top_srcdir)/gnulib/m4/ssize_t.m4 \ + $(top_srcdir)/gnulib/m4/stdarg.m4 \ + $(top_srcdir)/gnulib/m4/stdbool.m4 \ + $(top_srcdir)/gnulib/m4/stddef_h.m4 \ + $(top_srcdir)/gnulib/m4/stdint.m4 \ + $(top_srcdir)/gnulib/m4/stdint_h.m4 \ + $(top_srcdir)/gnulib/m4/stdio_h.m4 \ + $(top_srcdir)/gnulib/m4/stdlib_h.m4 \ + $(top_srcdir)/gnulib/m4/stpcpy.m4 \ + $(top_srcdir)/gnulib/m4/strcase.m4 \ + $(top_srcdir)/gnulib/m4/strcasestr.m4 \ + $(top_srcdir)/gnulib/m4/strdup.m4 \ + $(top_srcdir)/gnulib/m4/strerror.m4 \ + $(top_srcdir)/gnulib/m4/string_h.m4 \ + $(top_srcdir)/gnulib/m4/strings_h.m4 \ + $(top_srcdir)/gnulib/m4/strndup.m4 \ + $(top_srcdir)/gnulib/m4/strnlen.m4 \ + $(top_srcdir)/gnulib/m4/strstr.m4 \ + $(top_srcdir)/gnulib/m4/sys_socket_h.m4 \ + $(top_srcdir)/gnulib/m4/sys_types_h.m4 \ + $(top_srcdir)/gnulib/m4/threadlib.m4 \ + $(top_srcdir)/gnulib/m4/unistd_h.m4 \ + $(top_srcdir)/gnulib/m4/vasnprintf.m4 \ + $(top_srcdir)/gnulib/m4/vasprintf.m4 \ + $(top_srcdir)/gnulib/m4/warn-on-use.m4 \ + $(top_srcdir)/gnulib/m4/wchar_h.m4 \ + $(top_srcdir)/gnulib/m4/wchar_t.m4 \ + $(top_srcdir)/gnulib/m4/wcrtomb.m4 \ + $(top_srcdir)/gnulib/m4/wctype_h.m4 \ + $(top_srcdir)/gnulib/m4/wcwidth.m4 \ + $(top_srcdir)/gnulib/m4/wint_t.m4 \ + $(top_srcdir)/gnulib/m4/xalloc.m4 \ + $(top_srcdir)/gnulib/m4/xsize.m4 $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/version.texi \ + $(srcdir)/stamp-vti $(srcdir)/version-stnd.texi \ + $(srcdir)/stamp-1 $(am__DIST_COMMON) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +SOURCES = +DIST_SOURCES = +AM_V_DVIPS = $(am__v_DVIPS_@AM_V@) +am__v_DVIPS_ = $(am__v_DVIPS_@AM_DEFAULT_V@) +am__v_DVIPS_0 = @echo " DVIPS " $@; +am__v_DVIPS_1 = +AM_V_MAKEINFO = $(am__v_MAKEINFO_@AM_V@) +am__v_MAKEINFO_ = $(am__v_MAKEINFO_@AM_DEFAULT_V@) +am__v_MAKEINFO_0 = @echo " MAKEINFO" $@; +am__v_MAKEINFO_1 = +AM_V_INFOHTML = $(am__v_INFOHTML_@AM_V@) +am__v_INFOHTML_ = $(am__v_INFOHTML_@AM_DEFAULT_V@) +am__v_INFOHTML_0 = @echo " INFOHTML" $@; +am__v_INFOHTML_1 = +AM_V_TEXI2DVI = $(am__v_TEXI2DVI_@AM_V@) +am__v_TEXI2DVI_ = $(am__v_TEXI2DVI_@AM_DEFAULT_V@) +am__v_TEXI2DVI_0 = @echo " TEXI2DVI" $@; +am__v_TEXI2DVI_1 = +AM_V_TEXI2PDF = $(am__v_TEXI2PDF_@AM_V@) +am__v_TEXI2PDF_ = $(am__v_TEXI2PDF_@AM_DEFAULT_V@) +am__v_TEXI2PDF_0 = @echo " TEXI2PDF" $@; +am__v_TEXI2PDF_1 = +AM_V_texinfo = $(am__v_texinfo_@AM_V@) +am__v_texinfo_ = $(am__v_texinfo_@AM_DEFAULT_V@) +am__v_texinfo_0 = -q +am__v_texinfo_1 = +AM_V_texidevnull = $(am__v_texidevnull_@AM_V@) +am__v_texidevnull_ = $(am__v_texidevnull_@AM_DEFAULT_V@) +am__v_texidevnull_0 = > /dev/null +am__v_texidevnull_1 = +INFO_DEPS = texinfo.info info-stnd.info +TEXINFO_TEX = $(top_srcdir)/build-aux/texinfo.tex +am__TEXINFO_TEX_DIR = $(top_srcdir)/build-aux +DVIS = texinfo.dvi info-stnd.dvi +PDFS = texinfo.pdf info-stnd.pdf +PSS = texinfo.ps info-stnd.ps +HTMLS = texinfo.html info-stnd.html +TEXINFOS = texinfo.texi info-stnd.texi +TEXI2DVI = texi2dvi +TEXI2PDF = $(TEXI2DVI) --pdf --batch +MAKEINFOHTML = $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) +DVIPS = dvips +RECURSIVE_TARGETS = all-recursive check-recursive cscopelist-recursive \ + ctags-recursive dvi-recursive html-recursive info-recursive \ + install-data-recursive install-dvi-recursive \ + install-exec-recursive install-html-recursive \ + install-info-recursive install-pdf-recursive \ + install-ps-recursive install-recursive installcheck-recursive \ + installdirs-recursive pdf-recursive ps-recursive \ + tags-recursive uninstall-recursive +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__installdirs = "$(DESTDIR)$(infodir)" +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__uninstall_files_from_dir = { \ + test -z "$$files" \ + || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ + || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ + $(am__cd) "$$dir" && rm -f $$files; }; \ + } +RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \ + distclean-recursive maintainer-clean-recursive +am__recursive_targets = \ + $(RECURSIVE_TARGETS) \ + $(RECURSIVE_CLEAN_TARGETS) \ + $(am__extra_recursive_targets) +AM_RECURSIVE_TARGETS = $(am__recursive_targets:-recursive=) TAGS CTAGS \ + distdir distdir-am +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +# Read a list of newline-separated strings from the standard input, +# and print each of them once, without duplicates. Input order is +# *not* preserved. +am__uniquify_input = $(AWK) '\ + BEGIN { nonempty = 0; } \ + { items[$$0] = 1; nonempty = 1; } \ + END { if (nonempty) { for (i in items) print i; }; } \ +' +# Make sure the list of sources is unique. This is necessary because, +# e.g., the same source file might be shared among _SOURCES variables +# for different programs/libraries. +am__define_uniq_tagged_files = \ + list='$(am__tagged_files)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | $(am__uniquify_input)` +ETAGS = etags +CTAGS = ctags +DIST_SUBDIRS = $(SUBDIRS) +am__DIST_COMMON = $(srcdir)/Makefile.in \ + $(top_srcdir)/build-aux/mdate-sh \ + $(top_srcdir)/build-aux/texinfo.tex README texinfo.tex +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +am__relativize = \ + dir0=`pwd`; \ + sed_first='s,^\([^/]*\)/.*$$,\1,'; \ + sed_rest='s,^[^/]*/*,,'; \ + sed_last='s,^.*/\([^/]*\)$$,\1,'; \ + sed_butlast='s,/*[^/]*$$,,'; \ + while test -n "$$dir1"; do \ + first=`echo "$$dir1" | sed -e "$$sed_first"`; \ + if test "$$first" != "."; then \ + if test "$$first" = ".."; then \ + dir2=`echo "$$dir0" | sed -e "$$sed_last"`/"$$dir2"; \ + dir0=`echo "$$dir0" | sed -e "$$sed_butlast"`; \ + else \ + first2=`echo "$$dir2" | sed -e "$$sed_first"`; \ + if test "$$first2" = "$$first"; then \ + dir2=`echo "$$dir2" | sed -e "$$sed_rest"`; \ + else \ + dir2="../$$dir2"; \ + fi; \ + dir0="$$dir0"/"$$first"; \ + fi; \ + fi; \ + dir1=`echo "$$dir1" | sed -e "$$sed_rest"`; \ + done; \ + reldir="$$dir2" +ACLOCAL = @ACLOCAL@ +ALLOCA = @ALLOCA@ +ALLOCA_H = @ALLOCA_H@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +APPLE_UNIVERSAL_BUILD = @APPLE_UNIVERSAL_BUILD@ +AR = @AR@ +ARFLAGS = @ARFLAGS@ +ARGZ_H = @ARGZ_H@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BITSIZEOF_PTRDIFF_T = @BITSIZEOF_PTRDIFF_T@ +BITSIZEOF_SIG_ATOMIC_T = @BITSIZEOF_SIG_ATOMIC_T@ +BITSIZEOF_SIZE_T = @BITSIZEOF_SIZE_T@ +BITSIZEOF_WCHAR_T = @BITSIZEOF_WCHAR_T@ +BITSIZEOF_WINT_T = @BITSIZEOF_WINT_T@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DIFF_A_OPTION = @DIFF_A_OPTION@ +DIFF_U_OPTION = @DIFF_U_OPTION@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EMULTIHOP_HIDDEN = @EMULTIHOP_HIDDEN@ +EMULTIHOP_VALUE = @EMULTIHOP_VALUE@ +ENOLINK_HIDDEN = @ENOLINK_HIDDEN@ +ENOLINK_VALUE = @ENOLINK_VALUE@ +EOVERFLOW_HIDDEN = @EOVERFLOW_HIDDEN@ +EOVERFLOW_VALUE = @EOVERFLOW_VALUE@ +ERRNO_H = @ERRNO_H@ +EXEEXT = @EXEEXT@ +FLOAT_H = @FLOAT_H@ +GAWK = @GAWK@ +GETOPT_CDEFS_H = @GETOPT_CDEFS_H@ +GETOPT_H = @GETOPT_H@ +GETTEXT_MACRO_VERSION = @GETTEXT_MACRO_VERSION@ +GLIBC21 = @GLIBC21@ +GMSGFMT = @GMSGFMT@ +GMSGFMT_015 = @GMSGFMT_015@ +GNULIB_ATOLL = @GNULIB_ATOLL@ +GNULIB_BTOWC = @GNULIB_BTOWC@ +GNULIB_CALLOC_POSIX = @GNULIB_CALLOC_POSIX@ +GNULIB_CANONICALIZE_FILE_NAME = @GNULIB_CANONICALIZE_FILE_NAME@ +GNULIB_CHDIR = @GNULIB_CHDIR@ +GNULIB_CHOWN = @GNULIB_CHOWN@ +GNULIB_CLOSE = @GNULIB_CLOSE@ +GNULIB_DPRINTF = @GNULIB_DPRINTF@ +GNULIB_DUP = @GNULIB_DUP@ +GNULIB_DUP2 = @GNULIB_DUP2@ +GNULIB_DUP3 = @GNULIB_DUP3@ +GNULIB_DUPLOCALE = @GNULIB_DUPLOCALE@ +GNULIB_ENVIRON = @GNULIB_ENVIRON@ +GNULIB_EUIDACCESS = @GNULIB_EUIDACCESS@ +GNULIB_EXPLICIT_BZERO = @GNULIB_EXPLICIT_BZERO@ +GNULIB_FACCESSAT = @GNULIB_FACCESSAT@ +GNULIB_FCHDIR = @GNULIB_FCHDIR@ +GNULIB_FCHOWNAT = @GNULIB_FCHOWNAT@ +GNULIB_FCLOSE = @GNULIB_FCLOSE@ +GNULIB_FDATASYNC = @GNULIB_FDATASYNC@ +GNULIB_FDOPEN = @GNULIB_FDOPEN@ +GNULIB_FFLUSH = @GNULIB_FFLUSH@ +GNULIB_FFS = @GNULIB_FFS@ +GNULIB_FFSL = @GNULIB_FFSL@ +GNULIB_FFSLL = @GNULIB_FFSLL@ +GNULIB_FGETC = @GNULIB_FGETC@ +GNULIB_FGETS = @GNULIB_FGETS@ +GNULIB_FOPEN = @GNULIB_FOPEN@ +GNULIB_FPRINTF = @GNULIB_FPRINTF@ +GNULIB_FPRINTF_POSIX = @GNULIB_FPRINTF_POSIX@ +GNULIB_FPURGE = @GNULIB_FPURGE@ +GNULIB_FPUTC = @GNULIB_FPUTC@ +GNULIB_FPUTS = @GNULIB_FPUTS@ +GNULIB_FREAD = @GNULIB_FREAD@ +GNULIB_FREOPEN = @GNULIB_FREOPEN@ +GNULIB_FSCANF = @GNULIB_FSCANF@ +GNULIB_FSEEK = @GNULIB_FSEEK@ +GNULIB_FSEEKO = @GNULIB_FSEEKO@ +GNULIB_FSYNC = @GNULIB_FSYNC@ +GNULIB_FTELL = @GNULIB_FTELL@ +GNULIB_FTELLO = @GNULIB_FTELLO@ +GNULIB_FTRUNCATE = @GNULIB_FTRUNCATE@ +GNULIB_FWRITE = @GNULIB_FWRITE@ +GNULIB_GETC = @GNULIB_GETC@ +GNULIB_GETCHAR = @GNULIB_GETCHAR@ +GNULIB_GETCWD = @GNULIB_GETCWD@ +GNULIB_GETDELIM = @GNULIB_GETDELIM@ +GNULIB_GETDOMAINNAME = @GNULIB_GETDOMAINNAME@ +GNULIB_GETDTABLESIZE = @GNULIB_GETDTABLESIZE@ +GNULIB_GETGROUPS = @GNULIB_GETGROUPS@ +GNULIB_GETHOSTNAME = @GNULIB_GETHOSTNAME@ +GNULIB_GETLINE = @GNULIB_GETLINE@ +GNULIB_GETLOADAVG = @GNULIB_GETLOADAVG@ +GNULIB_GETLOGIN = @GNULIB_GETLOGIN@ +GNULIB_GETLOGIN_R = @GNULIB_GETLOGIN_R@ +GNULIB_GETPAGESIZE = @GNULIB_GETPAGESIZE@ +GNULIB_GETPASS = @GNULIB_GETPASS@ +GNULIB_GETSUBOPT = @GNULIB_GETSUBOPT@ +GNULIB_GETUSERSHELL = @GNULIB_GETUSERSHELL@ +GNULIB_GL_UNISTD_H_GETOPT = @GNULIB_GL_UNISTD_H_GETOPT@ +GNULIB_GRANTPT = @GNULIB_GRANTPT@ +GNULIB_GROUP_MEMBER = @GNULIB_GROUP_MEMBER@ +GNULIB_ISATTY = @GNULIB_ISATTY@ +GNULIB_ISWBLANK = @GNULIB_ISWBLANK@ +GNULIB_ISWCTYPE = @GNULIB_ISWCTYPE@ +GNULIB_LCHOWN = @GNULIB_LCHOWN@ +GNULIB_LINK = @GNULIB_LINK@ +GNULIB_LINKAT = @GNULIB_LINKAT@ +GNULIB_LOCALECONV = @GNULIB_LOCALECONV@ +GNULIB_LOCALENAME = @GNULIB_LOCALENAME@ +GNULIB_LSEEK = @GNULIB_LSEEK@ +GNULIB_MALLOC_POSIX = @GNULIB_MALLOC_POSIX@ +GNULIB_MBRLEN = @GNULIB_MBRLEN@ +GNULIB_MBRTOWC = @GNULIB_MBRTOWC@ +GNULIB_MBSCASECMP = @GNULIB_MBSCASECMP@ +GNULIB_MBSCASESTR = @GNULIB_MBSCASESTR@ +GNULIB_MBSCHR = @GNULIB_MBSCHR@ +GNULIB_MBSCSPN = @GNULIB_MBSCSPN@ +GNULIB_MBSINIT = @GNULIB_MBSINIT@ +GNULIB_MBSLEN = @GNULIB_MBSLEN@ +GNULIB_MBSNCASECMP = @GNULIB_MBSNCASECMP@ +GNULIB_MBSNLEN = @GNULIB_MBSNLEN@ +GNULIB_MBSNRTOWCS = @GNULIB_MBSNRTOWCS@ +GNULIB_MBSPBRK = @GNULIB_MBSPBRK@ +GNULIB_MBSPCASECMP = @GNULIB_MBSPCASECMP@ +GNULIB_MBSRCHR = @GNULIB_MBSRCHR@ +GNULIB_MBSRTOWCS = @GNULIB_MBSRTOWCS@ +GNULIB_MBSSEP = @GNULIB_MBSSEP@ +GNULIB_MBSSPN = @GNULIB_MBSSPN@ +GNULIB_MBSSTR = @GNULIB_MBSSTR@ +GNULIB_MBSTOK_R = @GNULIB_MBSTOK_R@ +GNULIB_MBTOWC = @GNULIB_MBTOWC@ +GNULIB_MEMCHR = @GNULIB_MEMCHR@ +GNULIB_MEMMEM = @GNULIB_MEMMEM@ +GNULIB_MEMPCPY = @GNULIB_MEMPCPY@ +GNULIB_MEMRCHR = @GNULIB_MEMRCHR@ +GNULIB_MKDTEMP = @GNULIB_MKDTEMP@ +GNULIB_MKOSTEMP = @GNULIB_MKOSTEMP@ +GNULIB_MKOSTEMPS = @GNULIB_MKOSTEMPS@ +GNULIB_MKSTEMP = @GNULIB_MKSTEMP@ +GNULIB_MKSTEMPS = @GNULIB_MKSTEMPS@ +GNULIB_NL_LANGINFO = @GNULIB_NL_LANGINFO@ +GNULIB_OBSTACK_PRINTF = @GNULIB_OBSTACK_PRINTF@ +GNULIB_OBSTACK_PRINTF_POSIX = @GNULIB_OBSTACK_PRINTF_POSIX@ +GNULIB_OVERRIDES_WINT_T = @GNULIB_OVERRIDES_WINT_T@ +GNULIB_PCLOSE = @GNULIB_PCLOSE@ +GNULIB_PERROR = @GNULIB_PERROR@ +GNULIB_PIPE = @GNULIB_PIPE@ +GNULIB_PIPE2 = @GNULIB_PIPE2@ +GNULIB_POPEN = @GNULIB_POPEN@ +GNULIB_POSIX_OPENPT = @GNULIB_POSIX_OPENPT@ +GNULIB_PREAD = @GNULIB_PREAD@ +GNULIB_PRINTF = @GNULIB_PRINTF@ +GNULIB_PRINTF_POSIX = @GNULIB_PRINTF_POSIX@ +GNULIB_PTSNAME = @GNULIB_PTSNAME@ +GNULIB_PTSNAME_R = @GNULIB_PTSNAME_R@ +GNULIB_PUTC = @GNULIB_PUTC@ +GNULIB_PUTCHAR = @GNULIB_PUTCHAR@ +GNULIB_PUTENV = @GNULIB_PUTENV@ +GNULIB_PUTS = @GNULIB_PUTS@ +GNULIB_PWRITE = @GNULIB_PWRITE@ +GNULIB_QSORT_R = @GNULIB_QSORT_R@ +GNULIB_RANDOM = @GNULIB_RANDOM@ +GNULIB_RANDOM_R = @GNULIB_RANDOM_R@ +GNULIB_RAWMEMCHR = @GNULIB_RAWMEMCHR@ +GNULIB_READ = @GNULIB_READ@ +GNULIB_READLINK = @GNULIB_READLINK@ +GNULIB_READLINKAT = @GNULIB_READLINKAT@ +GNULIB_REALLOCARRAY = @GNULIB_REALLOCARRAY@ +GNULIB_REALLOC_POSIX = @GNULIB_REALLOC_POSIX@ +GNULIB_REALPATH = @GNULIB_REALPATH@ +GNULIB_REMOVE = @GNULIB_REMOVE@ +GNULIB_RENAME = @GNULIB_RENAME@ +GNULIB_RENAMEAT = @GNULIB_RENAMEAT@ +GNULIB_RMDIR = @GNULIB_RMDIR@ +GNULIB_RPMATCH = @GNULIB_RPMATCH@ +GNULIB_SCANF = @GNULIB_SCANF@ +GNULIB_SECURE_GETENV = @GNULIB_SECURE_GETENV@ +GNULIB_SETENV = @GNULIB_SETENV@ +GNULIB_SETHOSTNAME = @GNULIB_SETHOSTNAME@ +GNULIB_SETLOCALE = @GNULIB_SETLOCALE@ +GNULIB_SLEEP = @GNULIB_SLEEP@ +GNULIB_SNPRINTF = @GNULIB_SNPRINTF@ +GNULIB_SPRINTF_POSIX = @GNULIB_SPRINTF_POSIX@ +GNULIB_STDIO_H_NONBLOCKING = @GNULIB_STDIO_H_NONBLOCKING@ +GNULIB_STDIO_H_SIGPIPE = @GNULIB_STDIO_H_SIGPIPE@ +GNULIB_STPCPY = @GNULIB_STPCPY@ +GNULIB_STPNCPY = @GNULIB_STPNCPY@ +GNULIB_STRCASESTR = @GNULIB_STRCASESTR@ +GNULIB_STRCHRNUL = @GNULIB_STRCHRNUL@ +GNULIB_STRDUP = @GNULIB_STRDUP@ +GNULIB_STRERROR = @GNULIB_STRERROR@ +GNULIB_STRERROR_R = @GNULIB_STRERROR_R@ +GNULIB_STRNCAT = @GNULIB_STRNCAT@ +GNULIB_STRNDUP = @GNULIB_STRNDUP@ +GNULIB_STRNLEN = @GNULIB_STRNLEN@ +GNULIB_STRPBRK = @GNULIB_STRPBRK@ +GNULIB_STRSEP = @GNULIB_STRSEP@ +GNULIB_STRSIGNAL = @GNULIB_STRSIGNAL@ +GNULIB_STRSTR = @GNULIB_STRSTR@ +GNULIB_STRTOD = @GNULIB_STRTOD@ +GNULIB_STRTOK_R = @GNULIB_STRTOK_R@ +GNULIB_STRTOLL = @GNULIB_STRTOLL@ +GNULIB_STRTOULL = @GNULIB_STRTOULL@ +GNULIB_STRVERSCMP = @GNULIB_STRVERSCMP@ +GNULIB_SYMLINK = @GNULIB_SYMLINK@ +GNULIB_SYMLINKAT = @GNULIB_SYMLINKAT@ +GNULIB_SYSTEM_POSIX = @GNULIB_SYSTEM_POSIX@ +GNULIB_TMPFILE = @GNULIB_TMPFILE@ +GNULIB_TOWCTRANS = @GNULIB_TOWCTRANS@ +GNULIB_TRUNCATE = @GNULIB_TRUNCATE@ +GNULIB_TTYNAME_R = @GNULIB_TTYNAME_R@ +GNULIB_UNISTD_H_NONBLOCKING = @GNULIB_UNISTD_H_NONBLOCKING@ +GNULIB_UNISTD_H_SIGPIPE = @GNULIB_UNISTD_H_SIGPIPE@ +GNULIB_UNLINK = @GNULIB_UNLINK@ +GNULIB_UNLINKAT = @GNULIB_UNLINKAT@ +GNULIB_UNLOCKPT = @GNULIB_UNLOCKPT@ +GNULIB_UNSETENV = @GNULIB_UNSETENV@ +GNULIB_USLEEP = @GNULIB_USLEEP@ +GNULIB_VASPRINTF = @GNULIB_VASPRINTF@ +GNULIB_VDPRINTF = @GNULIB_VDPRINTF@ +GNULIB_VFPRINTF = @GNULIB_VFPRINTF@ +GNULIB_VFPRINTF_POSIX = @GNULIB_VFPRINTF_POSIX@ +GNULIB_VFSCANF = @GNULIB_VFSCANF@ +GNULIB_VPRINTF = @GNULIB_VPRINTF@ +GNULIB_VPRINTF_POSIX = @GNULIB_VPRINTF_POSIX@ +GNULIB_VSCANF = @GNULIB_VSCANF@ +GNULIB_VSNPRINTF = @GNULIB_VSNPRINTF@ +GNULIB_VSPRINTF_POSIX = @GNULIB_VSPRINTF_POSIX@ +GNULIB_WCPCPY = @GNULIB_WCPCPY@ +GNULIB_WCPNCPY = @GNULIB_WCPNCPY@ +GNULIB_WCRTOMB = @GNULIB_WCRTOMB@ +GNULIB_WCSCASECMP = @GNULIB_WCSCASECMP@ +GNULIB_WCSCAT = @GNULIB_WCSCAT@ +GNULIB_WCSCHR = @GNULIB_WCSCHR@ +GNULIB_WCSCMP = @GNULIB_WCSCMP@ +GNULIB_WCSCOLL = @GNULIB_WCSCOLL@ +GNULIB_WCSCPY = @GNULIB_WCSCPY@ +GNULIB_WCSCSPN = @GNULIB_WCSCSPN@ +GNULIB_WCSDUP = @GNULIB_WCSDUP@ +GNULIB_WCSFTIME = @GNULIB_WCSFTIME@ +GNULIB_WCSLEN = @GNULIB_WCSLEN@ +GNULIB_WCSNCASECMP = @GNULIB_WCSNCASECMP@ +GNULIB_WCSNCAT = @GNULIB_WCSNCAT@ +GNULIB_WCSNCMP = @GNULIB_WCSNCMP@ +GNULIB_WCSNCPY = @GNULIB_WCSNCPY@ +GNULIB_WCSNLEN = @GNULIB_WCSNLEN@ +GNULIB_WCSNRTOMBS = @GNULIB_WCSNRTOMBS@ +GNULIB_WCSPBRK = @GNULIB_WCSPBRK@ +GNULIB_WCSRCHR = @GNULIB_WCSRCHR@ +GNULIB_WCSRTOMBS = @GNULIB_WCSRTOMBS@ +GNULIB_WCSSPN = @GNULIB_WCSSPN@ +GNULIB_WCSSTR = @GNULIB_WCSSTR@ +GNULIB_WCSTOK = @GNULIB_WCSTOK@ +GNULIB_WCSWIDTH = @GNULIB_WCSWIDTH@ +GNULIB_WCSXFRM = @GNULIB_WCSXFRM@ +GNULIB_WCTOB = @GNULIB_WCTOB@ +GNULIB_WCTOMB = @GNULIB_WCTOMB@ +GNULIB_WCTRANS = @GNULIB_WCTRANS@ +GNULIB_WCTYPE = @GNULIB_WCTYPE@ +GNULIB_WCWIDTH = @GNULIB_WCWIDTH@ +GNULIB_WMEMCHR = @GNULIB_WMEMCHR@ +GNULIB_WMEMCMP = @GNULIB_WMEMCMP@ +GNULIB_WMEMCPY = @GNULIB_WMEMCPY@ +GNULIB_WMEMMOVE = @GNULIB_WMEMMOVE@ +GNULIB_WMEMSET = @GNULIB_WMEMSET@ +GNULIB_WRITE = @GNULIB_WRITE@ +GNULIB__EXIT = @GNULIB__EXIT@ +GREP = @GREP@ +HAVE_ATOLL = @HAVE_ATOLL@ +HAVE_BTOWC = @HAVE_BTOWC@ +HAVE_C99_STDINT_H = @HAVE_C99_STDINT_H@ +HAVE_CANONICALIZE_FILE_NAME = @HAVE_CANONICALIZE_FILE_NAME@ +HAVE_CHOWN = @HAVE_CHOWN@ +HAVE_CRTDEFS_H = @HAVE_CRTDEFS_H@ +HAVE_DECL_ENVIRON = @HAVE_DECL_ENVIRON@ +HAVE_DECL_FCHDIR = @HAVE_DECL_FCHDIR@ +HAVE_DECL_FDATASYNC = @HAVE_DECL_FDATASYNC@ +HAVE_DECL_FPURGE = @HAVE_DECL_FPURGE@ +HAVE_DECL_FSEEKO = @HAVE_DECL_FSEEKO@ +HAVE_DECL_FTELLO = @HAVE_DECL_FTELLO@ +HAVE_DECL_GETDELIM = @HAVE_DECL_GETDELIM@ +HAVE_DECL_GETDOMAINNAME = @HAVE_DECL_GETDOMAINNAME@ +HAVE_DECL_GETLINE = @HAVE_DECL_GETLINE@ +HAVE_DECL_GETLOADAVG = @HAVE_DECL_GETLOADAVG@ +HAVE_DECL_GETLOGIN = @HAVE_DECL_GETLOGIN@ +HAVE_DECL_GETLOGIN_R = @HAVE_DECL_GETLOGIN_R@ +HAVE_DECL_GETPAGESIZE = @HAVE_DECL_GETPAGESIZE@ +HAVE_DECL_GETUSERSHELL = @HAVE_DECL_GETUSERSHELL@ +HAVE_DECL_INITSTATE = @HAVE_DECL_INITSTATE@ +HAVE_DECL_MEMMEM = @HAVE_DECL_MEMMEM@ +HAVE_DECL_MEMRCHR = @HAVE_DECL_MEMRCHR@ +HAVE_DECL_OBSTACK_PRINTF = @HAVE_DECL_OBSTACK_PRINTF@ +HAVE_DECL_SETENV = @HAVE_DECL_SETENV@ +HAVE_DECL_SETHOSTNAME = @HAVE_DECL_SETHOSTNAME@ +HAVE_DECL_SETSTATE = @HAVE_DECL_SETSTATE@ +HAVE_DECL_SNPRINTF = @HAVE_DECL_SNPRINTF@ +HAVE_DECL_STRDUP = @HAVE_DECL_STRDUP@ +HAVE_DECL_STRERROR_R = @HAVE_DECL_STRERROR_R@ +HAVE_DECL_STRNCASECMP = @HAVE_DECL_STRNCASECMP@ +HAVE_DECL_STRNDUP = @HAVE_DECL_STRNDUP@ +HAVE_DECL_STRNLEN = @HAVE_DECL_STRNLEN@ +HAVE_DECL_STRSIGNAL = @HAVE_DECL_STRSIGNAL@ +HAVE_DECL_STRTOK_R = @HAVE_DECL_STRTOK_R@ +HAVE_DECL_TRUNCATE = @HAVE_DECL_TRUNCATE@ +HAVE_DECL_TTYNAME_R = @HAVE_DECL_TTYNAME_R@ +HAVE_DECL_UNSETENV = @HAVE_DECL_UNSETENV@ +HAVE_DECL_VSNPRINTF = @HAVE_DECL_VSNPRINTF@ +HAVE_DECL_WCTOB = @HAVE_DECL_WCTOB@ +HAVE_DECL_WCWIDTH = @HAVE_DECL_WCWIDTH@ +HAVE_DPRINTF = @HAVE_DPRINTF@ +HAVE_DUP2 = @HAVE_DUP2@ +HAVE_DUP3 = @HAVE_DUP3@ +HAVE_DUPLOCALE = @HAVE_DUPLOCALE@ +HAVE_EUIDACCESS = @HAVE_EUIDACCESS@ +HAVE_EXPLICIT_BZERO = @HAVE_EXPLICIT_BZERO@ +HAVE_FACCESSAT = @HAVE_FACCESSAT@ +HAVE_FCHDIR = @HAVE_FCHDIR@ +HAVE_FCHOWNAT = @HAVE_FCHOWNAT@ +HAVE_FDATASYNC = @HAVE_FDATASYNC@ +HAVE_FEATURES_H = @HAVE_FEATURES_H@ +HAVE_FFS = @HAVE_FFS@ +HAVE_FFSL = @HAVE_FFSL@ +HAVE_FFSLL = @HAVE_FFSLL@ +HAVE_FREELOCALE = @HAVE_FREELOCALE@ +HAVE_FSEEKO = @HAVE_FSEEKO@ +HAVE_FSYNC = @HAVE_FSYNC@ +HAVE_FTELLO = @HAVE_FTELLO@ +HAVE_FTRUNCATE = @HAVE_FTRUNCATE@ +HAVE_GETDTABLESIZE = @HAVE_GETDTABLESIZE@ +HAVE_GETGROUPS = @HAVE_GETGROUPS@ +HAVE_GETHOSTNAME = @HAVE_GETHOSTNAME@ +HAVE_GETLOGIN = @HAVE_GETLOGIN@ +HAVE_GETOPT_H = @HAVE_GETOPT_H@ +HAVE_GETPAGESIZE = @HAVE_GETPAGESIZE@ +HAVE_GETPASS = @HAVE_GETPASS@ +HAVE_GETSUBOPT = @HAVE_GETSUBOPT@ +HAVE_GRANTPT = @HAVE_GRANTPT@ +HAVE_GROUP_MEMBER = @HAVE_GROUP_MEMBER@ +HAVE_INTTYPES_H = @HAVE_INTTYPES_H@ +HAVE_ISWBLANK = @HAVE_ISWBLANK@ +HAVE_ISWCNTRL = @HAVE_ISWCNTRL@ +HAVE_LANGINFO_ALTMON = @HAVE_LANGINFO_ALTMON@ +HAVE_LANGINFO_CODESET = @HAVE_LANGINFO_CODESET@ +HAVE_LANGINFO_ERA = @HAVE_LANGINFO_ERA@ +HAVE_LANGINFO_H = @HAVE_LANGINFO_H@ +HAVE_LANGINFO_T_FMT_AMPM = @HAVE_LANGINFO_T_FMT_AMPM@ +HAVE_LANGINFO_YESEXPR = @HAVE_LANGINFO_YESEXPR@ +HAVE_LCHOWN = @HAVE_LCHOWN@ +HAVE_LINK = @HAVE_LINK@ +HAVE_LINKAT = @HAVE_LINKAT@ +HAVE_LONG_LONG_INT = @HAVE_LONG_LONG_INT@ +HAVE_MAX_ALIGN_T = @HAVE_MAX_ALIGN_T@ +HAVE_MBRLEN = @HAVE_MBRLEN@ +HAVE_MBRTOWC = @HAVE_MBRTOWC@ +HAVE_MBSINIT = @HAVE_MBSINIT@ +HAVE_MBSLEN = @HAVE_MBSLEN@ +HAVE_MBSNRTOWCS = @HAVE_MBSNRTOWCS@ +HAVE_MBSRTOWCS = @HAVE_MBSRTOWCS@ +HAVE_MEMCHR = @HAVE_MEMCHR@ +HAVE_MEMPCPY = @HAVE_MEMPCPY@ +HAVE_MKDTEMP = @HAVE_MKDTEMP@ +HAVE_MKOSTEMP = @HAVE_MKOSTEMP@ +HAVE_MKOSTEMPS = @HAVE_MKOSTEMPS@ +HAVE_MKSTEMP = @HAVE_MKSTEMP@ +HAVE_MKSTEMPS = @HAVE_MKSTEMPS@ +HAVE_MSVC_INVALID_PARAMETER_HANDLER = @HAVE_MSVC_INVALID_PARAMETER_HANDLER@ +HAVE_NEWLOCALE = @HAVE_NEWLOCALE@ +HAVE_NL_LANGINFO = @HAVE_NL_LANGINFO@ +HAVE_OS_H = @HAVE_OS_H@ +HAVE_PCLOSE = @HAVE_PCLOSE@ +HAVE_PIPE = @HAVE_PIPE@ +HAVE_PIPE2 = @HAVE_PIPE2@ +HAVE_POPEN = @HAVE_POPEN@ +HAVE_POSIX_OPENPT = @HAVE_POSIX_OPENPT@ +HAVE_PREAD = @HAVE_PREAD@ +HAVE_PTSNAME = @HAVE_PTSNAME@ +HAVE_PTSNAME_R = @HAVE_PTSNAME_R@ +HAVE_PWRITE = @HAVE_PWRITE@ +HAVE_QSORT_R = @HAVE_QSORT_R@ +HAVE_RANDOM = @HAVE_RANDOM@ +HAVE_RANDOM_H = @HAVE_RANDOM_H@ +HAVE_RANDOM_R = @HAVE_RANDOM_R@ +HAVE_RAWMEMCHR = @HAVE_RAWMEMCHR@ +HAVE_READLINK = @HAVE_READLINK@ +HAVE_READLINKAT = @HAVE_READLINKAT@ +HAVE_REALLOCARRAY = @HAVE_REALLOCARRAY@ +HAVE_REALPATH = @HAVE_REALPATH@ +HAVE_RENAMEAT = @HAVE_RENAMEAT@ +HAVE_RPMATCH = @HAVE_RPMATCH@ +HAVE_SECURE_GETENV = @HAVE_SECURE_GETENV@ +HAVE_SETENV = @HAVE_SETENV@ +HAVE_SETHOSTNAME = @HAVE_SETHOSTNAME@ +HAVE_SIGNED_SIG_ATOMIC_T = @HAVE_SIGNED_SIG_ATOMIC_T@ +HAVE_SIGNED_WCHAR_T = @HAVE_SIGNED_WCHAR_T@ +HAVE_SIGNED_WINT_T = @HAVE_SIGNED_WINT_T@ +HAVE_SLEEP = @HAVE_SLEEP@ +HAVE_STDINT_H = @HAVE_STDINT_H@ +HAVE_STPCPY = @HAVE_STPCPY@ +HAVE_STPNCPY = @HAVE_STPNCPY@ +HAVE_STRCASECMP = @HAVE_STRCASECMP@ +HAVE_STRCASESTR = @HAVE_STRCASESTR@ +HAVE_STRCHRNUL = @HAVE_STRCHRNUL@ +HAVE_STRINGS_H = @HAVE_STRINGS_H@ +HAVE_STRPBRK = @HAVE_STRPBRK@ +HAVE_STRSEP = @HAVE_STRSEP@ +HAVE_STRTOD = @HAVE_STRTOD@ +HAVE_STRTOLL = @HAVE_STRTOLL@ +HAVE_STRTOULL = @HAVE_STRTOULL@ +HAVE_STRUCT_RANDOM_DATA = @HAVE_STRUCT_RANDOM_DATA@ +HAVE_STRVERSCMP = @HAVE_STRVERSCMP@ +HAVE_SYMLINK = @HAVE_SYMLINK@ +HAVE_SYMLINKAT = @HAVE_SYMLINKAT@ +HAVE_SYS_BITYPES_H = @HAVE_SYS_BITYPES_H@ +HAVE_SYS_CDEFS_H = @HAVE_SYS_CDEFS_H@ +HAVE_SYS_INTTYPES_H = @HAVE_SYS_INTTYPES_H@ +HAVE_SYS_LOADAVG_H = @HAVE_SYS_LOADAVG_H@ +HAVE_SYS_PARAM_H = @HAVE_SYS_PARAM_H@ +HAVE_SYS_TYPES_H = @HAVE_SYS_TYPES_H@ +HAVE_UNISTD_H = @HAVE_UNISTD_H@ +HAVE_UNLINKAT = @HAVE_UNLINKAT@ +HAVE_UNLOCKPT = @HAVE_UNLOCKPT@ +HAVE_UNSIGNED_LONG_LONG_INT = @HAVE_UNSIGNED_LONG_LONG_INT@ +HAVE_USLEEP = @HAVE_USLEEP@ +HAVE_VASPRINTF = @HAVE_VASPRINTF@ +HAVE_VDPRINTF = @HAVE_VDPRINTF@ +HAVE_WCHAR_H = @HAVE_WCHAR_H@ +HAVE_WCHAR_T = @HAVE_WCHAR_T@ +HAVE_WCPCPY = @HAVE_WCPCPY@ +HAVE_WCPNCPY = @HAVE_WCPNCPY@ +HAVE_WCRTOMB = @HAVE_WCRTOMB@ +HAVE_WCSCASECMP = @HAVE_WCSCASECMP@ +HAVE_WCSCAT = @HAVE_WCSCAT@ +HAVE_WCSCHR = @HAVE_WCSCHR@ +HAVE_WCSCMP = @HAVE_WCSCMP@ +HAVE_WCSCOLL = @HAVE_WCSCOLL@ +HAVE_WCSCPY = @HAVE_WCSCPY@ +HAVE_WCSCSPN = @HAVE_WCSCSPN@ +HAVE_WCSDUP = @HAVE_WCSDUP@ +HAVE_WCSFTIME = @HAVE_WCSFTIME@ +HAVE_WCSLEN = @HAVE_WCSLEN@ +HAVE_WCSNCASECMP = @HAVE_WCSNCASECMP@ +HAVE_WCSNCAT = @HAVE_WCSNCAT@ +HAVE_WCSNCMP = @HAVE_WCSNCMP@ +HAVE_WCSNCPY = @HAVE_WCSNCPY@ +HAVE_WCSNLEN = @HAVE_WCSNLEN@ +HAVE_WCSNRTOMBS = @HAVE_WCSNRTOMBS@ +HAVE_WCSPBRK = @HAVE_WCSPBRK@ +HAVE_WCSRCHR = @HAVE_WCSRCHR@ +HAVE_WCSRTOMBS = @HAVE_WCSRTOMBS@ +HAVE_WCSSPN = @HAVE_WCSSPN@ +HAVE_WCSSTR = @HAVE_WCSSTR@ +HAVE_WCSTOK = @HAVE_WCSTOK@ +HAVE_WCSWIDTH = @HAVE_WCSWIDTH@ +HAVE_WCSXFRM = @HAVE_WCSXFRM@ +HAVE_WCTRANS_T = @HAVE_WCTRANS_T@ +HAVE_WCTYPE_H = @HAVE_WCTYPE_H@ +HAVE_WCTYPE_T = @HAVE_WCTYPE_T@ +HAVE_WINSOCK2_H = @HAVE_WINSOCK2_H@ +HAVE_WINT_T = @HAVE_WINT_T@ +HAVE_WMEMCHR = @HAVE_WMEMCHR@ +HAVE_WMEMCMP = @HAVE_WMEMCMP@ +HAVE_WMEMCPY = @HAVE_WMEMCPY@ +HAVE_WMEMMOVE = @HAVE_WMEMMOVE@ +HAVE_WMEMSET = @HAVE_WMEMSET@ +HAVE_XLOCALE_H = @HAVE_XLOCALE_H@ +HAVE__BOOL = @HAVE__BOOL@ +HAVE__EXIT = @HAVE__EXIT@ +HELP2MAN = @HELP2MAN@ +INCLUDE_NEXT = @INCLUDE_NEXT@ +INCLUDE_NEXT_AS_FIRST_DIRECTIVE = @INCLUDE_NEXT_AS_FIRST_DIRECTIVE@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +INTLLIBS = @INTLLIBS@ +INTL_MACOSX_LIBS = @INTL_MACOSX_LIBS@ +LDFLAGS = @LDFLAGS@ +LIBGNU_LIBDEPS = @LIBGNU_LIBDEPS@ +LIBGNU_LTLIBDEPS = @LIBGNU_LTLIBDEPS@ +LIBICONV = @LIBICONV@ +LIBINTL = @LIBINTL@ +LIBMULTITHREAD = @LIBMULTITHREAD@ +LIBOBJS = @LIBOBJS@ +LIBPTH = @LIBPTH@ +LIBPTH_PREFIX = @LIBPTH_PREFIX@ +LIBS = @LIBS@ +LIBTHREAD = @LIBTHREAD@ +LIBUNISTRING_UNITYPES_H = @LIBUNISTRING_UNITYPES_H@ +LIBUNISTRING_UNIWIDTH_H = @LIBUNISTRING_UNIWIDTH_H@ +LIMITS_H = @LIMITS_H@ +LN_S = @LN_S@ +LOCALCHARSET_TESTS_ENVIRONMENT = @LOCALCHARSET_TESTS_ENVIRONMENT@ +LOCALE_FR = @LOCALE_FR@ +LOCALE_FR_UTF8 = @LOCALE_FR_UTF8@ +LOCALE_JA = @LOCALE_JA@ +LOCALE_ZH_CN = @LOCALE_ZH_CN@ +LTLIBICONV = @LTLIBICONV@ +LTLIBINTL = @LTLIBINTL@ +LTLIBMULTITHREAD = @LTLIBMULTITHREAD@ +LTLIBOBJS = @LTLIBOBJS@ +LTLIBPTH = @LTLIBPTH@ +LTLIBTHREAD = @LTLIBTHREAD@ +MAKEINFO = $(MAKEINFO_ENVIRONMENT) $(PERL) $(top_builddir)/tp/texi2any +MKDIR_P = @MKDIR_P@ +MKINSTALLDIRS = @MKINSTALLDIRS@ +MSGFMT = @MSGFMT@ +MSGFMT_015 = @MSGFMT_015@ +MSGMERGE = @MSGMERGE@ +NEXT_AS_FIRST_DIRECTIVE_ERRNO_H = @NEXT_AS_FIRST_DIRECTIVE_ERRNO_H@ +NEXT_AS_FIRST_DIRECTIVE_FLOAT_H = @NEXT_AS_FIRST_DIRECTIVE_FLOAT_H@ +NEXT_AS_FIRST_DIRECTIVE_GETOPT_H = @NEXT_AS_FIRST_DIRECTIVE_GETOPT_H@ +NEXT_AS_FIRST_DIRECTIVE_LANGINFO_H = @NEXT_AS_FIRST_DIRECTIVE_LANGINFO_H@ +NEXT_AS_FIRST_DIRECTIVE_LIMITS_H = @NEXT_AS_FIRST_DIRECTIVE_LIMITS_H@ +NEXT_AS_FIRST_DIRECTIVE_LOCALE_H = @NEXT_AS_FIRST_DIRECTIVE_LOCALE_H@ +NEXT_AS_FIRST_DIRECTIVE_STDARG_H = @NEXT_AS_FIRST_DIRECTIVE_STDARG_H@ +NEXT_AS_FIRST_DIRECTIVE_STDDEF_H = @NEXT_AS_FIRST_DIRECTIVE_STDDEF_H@ +NEXT_AS_FIRST_DIRECTIVE_STDINT_H = @NEXT_AS_FIRST_DIRECTIVE_STDINT_H@ +NEXT_AS_FIRST_DIRECTIVE_STDIO_H = @NEXT_AS_FIRST_DIRECTIVE_STDIO_H@ +NEXT_AS_FIRST_DIRECTIVE_STDLIB_H = @NEXT_AS_FIRST_DIRECTIVE_STDLIB_H@ +NEXT_AS_FIRST_DIRECTIVE_STRINGS_H = @NEXT_AS_FIRST_DIRECTIVE_STRINGS_H@ +NEXT_AS_FIRST_DIRECTIVE_STRING_H = @NEXT_AS_FIRST_DIRECTIVE_STRING_H@ +NEXT_AS_FIRST_DIRECTIVE_SYS_TYPES_H = @NEXT_AS_FIRST_DIRECTIVE_SYS_TYPES_H@ +NEXT_AS_FIRST_DIRECTIVE_UNISTD_H = @NEXT_AS_FIRST_DIRECTIVE_UNISTD_H@ +NEXT_AS_FIRST_DIRECTIVE_WCHAR_H = @NEXT_AS_FIRST_DIRECTIVE_WCHAR_H@ +NEXT_AS_FIRST_DIRECTIVE_WCTYPE_H = @NEXT_AS_FIRST_DIRECTIVE_WCTYPE_H@ +NEXT_ERRNO_H = @NEXT_ERRNO_H@ +NEXT_FLOAT_H = @NEXT_FLOAT_H@ +NEXT_GETOPT_H = @NEXT_GETOPT_H@ +NEXT_LANGINFO_H = @NEXT_LANGINFO_H@ +NEXT_LIMITS_H = @NEXT_LIMITS_H@ +NEXT_LOCALE_H = @NEXT_LOCALE_H@ +NEXT_STDARG_H = @NEXT_STDARG_H@ +NEXT_STDDEF_H = @NEXT_STDDEF_H@ +NEXT_STDINT_H = @NEXT_STDINT_H@ +NEXT_STDIO_H = @NEXT_STDIO_H@ +NEXT_STDLIB_H = @NEXT_STDLIB_H@ +NEXT_STRINGS_H = @NEXT_STRINGS_H@ +NEXT_STRING_H = @NEXT_STRING_H@ +NEXT_SYS_TYPES_H = @NEXT_SYS_TYPES_H@ +NEXT_UNISTD_H = @NEXT_UNISTD_H@ +NEXT_WCHAR_H = @NEXT_WCHAR_H@ +NEXT_WCTYPE_H = @NEXT_WCTYPE_H@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_DATE = @PACKAGE_DATE@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +PERL_EXT_CC = @PERL_EXT_CC@ +PERL_EXT_CFLAGS = @PERL_EXT_CFLAGS@ +PERL_EXT_CPPFLAGS = @PERL_EXT_CPPFLAGS@ +PERL_EXT_LDFLAGS = @PERL_EXT_LDFLAGS@ +POD2MAN = @POD2MAN@ +POSUB = @POSUB@ +PRAGMA_COLUMNS = @PRAGMA_COLUMNS@ +PRAGMA_SYSTEM_HEADER = @PRAGMA_SYSTEM_HEADER@ +PROVE = @PROVE@ +PTRDIFF_T_SUFFIX = @PTRDIFF_T_SUFFIX@ +RANLIB = @RANLIB@ +REPLACE_BTOWC = @REPLACE_BTOWC@ +REPLACE_CALLOC = @REPLACE_CALLOC@ +REPLACE_CANONICALIZE_FILE_NAME = @REPLACE_CANONICALIZE_FILE_NAME@ +REPLACE_CHOWN = @REPLACE_CHOWN@ +REPLACE_CLOSE = @REPLACE_CLOSE@ +REPLACE_DPRINTF = @REPLACE_DPRINTF@ +REPLACE_DUP = @REPLACE_DUP@ +REPLACE_DUP2 = @REPLACE_DUP2@ +REPLACE_DUPLOCALE = @REPLACE_DUPLOCALE@ +REPLACE_FACCESSAT = @REPLACE_FACCESSAT@ +REPLACE_FCHOWNAT = @REPLACE_FCHOWNAT@ +REPLACE_FCLOSE = @REPLACE_FCLOSE@ +REPLACE_FDOPEN = @REPLACE_FDOPEN@ +REPLACE_FFLUSH = @REPLACE_FFLUSH@ +REPLACE_FOPEN = @REPLACE_FOPEN@ +REPLACE_FPRINTF = @REPLACE_FPRINTF@ +REPLACE_FPURGE = @REPLACE_FPURGE@ +REPLACE_FREELOCALE = @REPLACE_FREELOCALE@ +REPLACE_FREOPEN = @REPLACE_FREOPEN@ +REPLACE_FSEEK = @REPLACE_FSEEK@ +REPLACE_FSEEKO = @REPLACE_FSEEKO@ +REPLACE_FTELL = @REPLACE_FTELL@ +REPLACE_FTELLO = @REPLACE_FTELLO@ +REPLACE_FTRUNCATE = @REPLACE_FTRUNCATE@ +REPLACE_GETCWD = @REPLACE_GETCWD@ +REPLACE_GETDELIM = @REPLACE_GETDELIM@ +REPLACE_GETDOMAINNAME = @REPLACE_GETDOMAINNAME@ +REPLACE_GETDTABLESIZE = @REPLACE_GETDTABLESIZE@ +REPLACE_GETGROUPS = @REPLACE_GETGROUPS@ +REPLACE_GETLINE = @REPLACE_GETLINE@ +REPLACE_GETLOGIN_R = @REPLACE_GETLOGIN_R@ +REPLACE_GETPAGESIZE = @REPLACE_GETPAGESIZE@ +REPLACE_GETPASS = @REPLACE_GETPASS@ +REPLACE_ISATTY = @REPLACE_ISATTY@ +REPLACE_ISWBLANK = @REPLACE_ISWBLANK@ +REPLACE_ISWCNTRL = @REPLACE_ISWCNTRL@ +REPLACE_ITOLD = @REPLACE_ITOLD@ +REPLACE_LCHOWN = @REPLACE_LCHOWN@ +REPLACE_LINK = @REPLACE_LINK@ +REPLACE_LINKAT = @REPLACE_LINKAT@ +REPLACE_LOCALECONV = @REPLACE_LOCALECONV@ +REPLACE_LSEEK = @REPLACE_LSEEK@ +REPLACE_MALLOC = @REPLACE_MALLOC@ +REPLACE_MBRLEN = @REPLACE_MBRLEN@ +REPLACE_MBRTOWC = @REPLACE_MBRTOWC@ +REPLACE_MBSINIT = @REPLACE_MBSINIT@ +REPLACE_MBSNRTOWCS = @REPLACE_MBSNRTOWCS@ +REPLACE_MBSRTOWCS = @REPLACE_MBSRTOWCS@ +REPLACE_MBSTATE_T = @REPLACE_MBSTATE_T@ +REPLACE_MBTOWC = @REPLACE_MBTOWC@ +REPLACE_MEMCHR = @REPLACE_MEMCHR@ +REPLACE_MEMMEM = @REPLACE_MEMMEM@ +REPLACE_MKSTEMP = @REPLACE_MKSTEMP@ +REPLACE_NEWLOCALE = @REPLACE_NEWLOCALE@ +REPLACE_NL_LANGINFO = @REPLACE_NL_LANGINFO@ +REPLACE_NULL = @REPLACE_NULL@ +REPLACE_OBSTACK_PRINTF = @REPLACE_OBSTACK_PRINTF@ +REPLACE_PERROR = @REPLACE_PERROR@ +REPLACE_POPEN = @REPLACE_POPEN@ +REPLACE_PREAD = @REPLACE_PREAD@ +REPLACE_PRINTF = @REPLACE_PRINTF@ +REPLACE_PTSNAME = @REPLACE_PTSNAME@ +REPLACE_PTSNAME_R = @REPLACE_PTSNAME_R@ +REPLACE_PUTENV = @REPLACE_PUTENV@ +REPLACE_PWRITE = @REPLACE_PWRITE@ +REPLACE_QSORT_R = @REPLACE_QSORT_R@ +REPLACE_RANDOM_R = @REPLACE_RANDOM_R@ +REPLACE_READ = @REPLACE_READ@ +REPLACE_READLINK = @REPLACE_READLINK@ +REPLACE_READLINKAT = @REPLACE_READLINKAT@ +REPLACE_REALLOC = @REPLACE_REALLOC@ +REPLACE_REALPATH = @REPLACE_REALPATH@ +REPLACE_REMOVE = @REPLACE_REMOVE@ +REPLACE_RENAME = @REPLACE_RENAME@ +REPLACE_RENAMEAT = @REPLACE_RENAMEAT@ +REPLACE_RMDIR = @REPLACE_RMDIR@ +REPLACE_SETENV = @REPLACE_SETENV@ +REPLACE_SETLOCALE = @REPLACE_SETLOCALE@ +REPLACE_SLEEP = @REPLACE_SLEEP@ +REPLACE_SNPRINTF = @REPLACE_SNPRINTF@ +REPLACE_SPRINTF = @REPLACE_SPRINTF@ +REPLACE_STDIO_READ_FUNCS = @REPLACE_STDIO_READ_FUNCS@ +REPLACE_STDIO_WRITE_FUNCS = @REPLACE_STDIO_WRITE_FUNCS@ +REPLACE_STPNCPY = @REPLACE_STPNCPY@ +REPLACE_STRCASESTR = @REPLACE_STRCASESTR@ +REPLACE_STRCHRNUL = @REPLACE_STRCHRNUL@ +REPLACE_STRDUP = @REPLACE_STRDUP@ +REPLACE_STRERROR = @REPLACE_STRERROR@ +REPLACE_STRERROR_R = @REPLACE_STRERROR_R@ +REPLACE_STRNCAT = @REPLACE_STRNCAT@ +REPLACE_STRNDUP = @REPLACE_STRNDUP@ +REPLACE_STRNLEN = @REPLACE_STRNLEN@ +REPLACE_STRSIGNAL = @REPLACE_STRSIGNAL@ +REPLACE_STRSTR = @REPLACE_STRSTR@ +REPLACE_STRTOD = @REPLACE_STRTOD@ +REPLACE_STRTOK_R = @REPLACE_STRTOK_R@ +REPLACE_STRUCT_LCONV = @REPLACE_STRUCT_LCONV@ +REPLACE_SYMLINK = @REPLACE_SYMLINK@ +REPLACE_SYMLINKAT = @REPLACE_SYMLINKAT@ +REPLACE_TMPFILE = @REPLACE_TMPFILE@ +REPLACE_TOWLOWER = @REPLACE_TOWLOWER@ +REPLACE_TRUNCATE = @REPLACE_TRUNCATE@ +REPLACE_TTYNAME_R = @REPLACE_TTYNAME_R@ +REPLACE_UNLINK = @REPLACE_UNLINK@ +REPLACE_UNLINKAT = @REPLACE_UNLINKAT@ +REPLACE_UNSETENV = @REPLACE_UNSETENV@ +REPLACE_USLEEP = @REPLACE_USLEEP@ +REPLACE_VASPRINTF = @REPLACE_VASPRINTF@ +REPLACE_VDPRINTF = @REPLACE_VDPRINTF@ +REPLACE_VFPRINTF = @REPLACE_VFPRINTF@ +REPLACE_VPRINTF = @REPLACE_VPRINTF@ +REPLACE_VSNPRINTF = @REPLACE_VSNPRINTF@ +REPLACE_VSPRINTF = @REPLACE_VSPRINTF@ +REPLACE_WCRTOMB = @REPLACE_WCRTOMB@ +REPLACE_WCSFTIME = @REPLACE_WCSFTIME@ +REPLACE_WCSNRTOMBS = @REPLACE_WCSNRTOMBS@ +REPLACE_WCSRTOMBS = @REPLACE_WCSRTOMBS@ +REPLACE_WCSWIDTH = @REPLACE_WCSWIDTH@ +REPLACE_WCTOB = @REPLACE_WCTOB@ +REPLACE_WCTOMB = @REPLACE_WCTOMB@ +REPLACE_WCWIDTH = @REPLACE_WCWIDTH@ +REPLACE_WRITE = @REPLACE_WRITE@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SIG_ATOMIC_T_SUFFIX = @SIG_ATOMIC_T_SUFFIX@ +SIZE_T_SUFFIX = @SIZE_T_SUFFIX@ +STDARG_H = @STDARG_H@ +STDBOOL_H = @STDBOOL_H@ +STDDEF_H = @STDDEF_H@ +STDINT_H = @STDINT_H@ +STRIP = @STRIP@ +TERMLIBS = @TERMLIBS@ +TEXINFO_DTD_VERSION = @TEXINFO_DTD_VERSION@ +UNDEFINE_STRTOK_R = @UNDEFINE_STRTOK_R@ +UNISTD_H_HAVE_WINSOCK2_H = @UNISTD_H_HAVE_WINSOCK2_H@ +UNISTD_H_HAVE_WINSOCK2_H_AND_USE_SOCKETS = @UNISTD_H_HAVE_WINSOCK2_H_AND_USE_SOCKETS@ +USE_EXTERNAL_EASTASIANWIDTH = @USE_EXTERNAL_EASTASIANWIDTH@ +USE_EXTERNAL_LIBINTL = @USE_EXTERNAL_LIBINTL@ +USE_EXTERNAL_UNIDECODE = @USE_EXTERNAL_UNIDECODE@ +USE_NLS = @USE_NLS@ +USE_UNICODE = @USE_UNICODE@ +VERSION = @VERSION@ +WCHAR_T_SUFFIX = @WCHAR_T_SUFFIX@ +WINDOWS_64_BIT_OFF_T = @WINDOWS_64_BIT_OFF_T@ +WINDOWS_STAT_INODES = @WINDOWS_STAT_INODES@ +WINT_T_SUFFIX = @WINT_T_SUFFIX@ +XGETTEXT = @XGETTEXT@ +XGETTEXT_015 = @XGETTEXT_015@ +XGETTEXT_EXTRA_OPTIONS = @XGETTEXT_EXTRA_OPTIONS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +enable_xs = @enable_xs@ +exec_prefix = @exec_prefix@ +gl_LIBOBJS = @gl_LIBOBJS@ +gl_LTLIBOBJS = @gl_LTLIBOBJS@ +gltests_LIBOBJS = @gltests_LIBOBJS@ +gltests_LTLIBOBJS = @gltests_LTLIBOBJS@ +gltests_WITNESS = @gltests_WITNESS@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +native_tools = @native_tools@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +SUBDIRS = tp_api +info_TEXINFOS = texinfo.texi info-stnd.texi +DISTCLEANFILES = texinfo.info* info-stnd.info* +MAKEINFO_ENVIRONMENT = TEXINFO_DEV_SOURCE=1 ; export TEXINFO_DEV_SOURCE ; \ + top_srcdir="$(top_srcdir)" ; export top_srcdir ; \ + top_builddir="$(top_builddir)" ; export top_builddir ; + + +# We'd also like to use something like this, but Automake calls +# "install-info" directly. +# INSTALL_INFO = $(top_builddir)/$(native_tools)/util/ginstall-info +TXI_XLATE = txi-ca.tex txi-cs.tex txi-de.tex txi-en.tex txi-es.tex \ + txi-fr.tex txi-hu.tex txi-is.tex txi-it.tex txi-ja.tex \ + txi-nb.tex txi-nl.tex txi-nn.tex txi-pl.tex txi-pt.tex \ + txi-ru.tex txi-sr.tex txi-tr.tex txi-uk.tex + +refcard_files = refcard/Makefile refcard/txicmdcheck \ + refcard/txirefcard-a4.pdf refcard/txirefcard.pdf \ + refcard/txirefcard.tex + + +# Include our texinfo.tex, not Automake's. +EXTRA_DIST = epsf.tex texinfo.tex \ + fdl.texi \ + $(man_MANS) $(TXI_XLATE) \ + $(refcard_files) \ + texinfo-tex-test.texi texinfo-tex-test.WIDOWs \ + texinfo-ja.tex short-sample-ja.texi + +texmf_texinfo = $(TEXMF)/tex/texinfo +texmf_dvips = $(TEXMF)/tex/generic/epsf + +# Rules for updating the online web pages for the documentation +# using the gendocs.sh script; see +# http://www.gnu.org/prep/maintain/html_node/Invoking-gendocs_002esh.html +# +# Invoke gendocs.sh from a gnulib checkout (outside our tree). +# +gnulib = $(abs_top_srcdir)/../gnulib +gendocs = $(gnulib)/build-aux/gendocs.sh +gendocs_templates = $(gnulib)/doc +gendocs_envvars = GENDOCS_TEMPLATE_DIR=$(gendocs_templates) +# +gendocs_email = bug-texinfo@gnu.org +gendocs_dir_url = /manual/ +gendocs_invoke = env $(gendocs_envvars) $(gendocs) --email $(gendocs_email) \ + --html '-c TOP_NODE_UP_URL=$(gendocs_dir_url)' + +# A nice side effect of using --html is to eliminate the fancy css default; +# otherwise, we could use gendocs_template_min. +# +manual1 = info-stnd +manual1_title = "GNU standalone info manual" +# +manual2 = texinfo +manual2_title = "GNU Texinfo manual" +# +# We also make a little HTML document for pod2texi script. +pod2texi_pl = $(abs_top_srcdir)/Pod-Simple-Texinfo/pod2texi.pl + +# destination directory. +doctemp = wwwtemp +www_target = $(HOME)/gnu/www/texinfo/manual +all: all-recursive + +.SUFFIXES: +.SUFFIXES: .dvi .ps +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +texinfo.info: texinfo.texi $(srcdir)/version.texi + $(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ `test -f 'texinfo.texi' || echo '$(srcdir)/'`texinfo.texi; \ + then \ + rc=0; \ + else \ + rc=$$?; \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +texinfo.dvi: texinfo.texi $(srcdir)/version.texi + $(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \ + `test -f 'texinfo.texi' || echo '$(srcdir)/'`texinfo.texi + +texinfo.pdf: texinfo.texi $(srcdir)/version.texi + $(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \ + `test -f 'texinfo.texi' || echo '$(srcdir)/'`texinfo.texi + +texinfo.html: texinfo.texi $(srcdir)/version.texi + $(AM_V_MAKEINFO)rm -rf $(@:.html=.htp) + $(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) `test -f 'texinfo.texi' || echo '$(srcdir)/'`texinfo.texi; \ + then \ + rm -rf $@ && mv $(@:.html=.htp) $@; \ + else \ + rm -rf $(@:.html=.htp); exit 1; \ + fi +$(srcdir)/version.texi: $(srcdir)/stamp-vti +$(srcdir)/stamp-vti: texinfo.texi $(top_srcdir)/configure + @(dir=.; test -f ./texinfo.texi || dir=$(srcdir); \ + set `$(SHELL) $(top_srcdir)/build-aux/mdate-sh $$dir/texinfo.texi`; \ + echo "@set UPDATED $$1 $$2 $$3"; \ + echo "@set UPDATED-MONTH $$2 $$3"; \ + echo "@set EDITION $(VERSION)"; \ + echo "@set VERSION $(VERSION)") > vti.tmp$$$$ && \ + (cmp -s vti.tmp$$$$ $(srcdir)/version.texi \ + || (echo "Updating $(srcdir)/version.texi" && \ + cp vti.tmp$$$$ $(srcdir)/version.texi.tmp$$$$ && \ + mv $(srcdir)/version.texi.tmp$$$$ $(srcdir)/version.texi)) && \ + rm -f vti.tmp$$$$ $(srcdir)/version.texi.$$$$ + @cp $(srcdir)/version.texi $@ + +mostlyclean-vti: + -rm -f vti.tmp* $(srcdir)/version.texi.tmp* + +maintainer-clean-vti: + -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi + +info-stnd.info: info-stnd.texi $(srcdir)/version-stnd.texi + $(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ `test -f 'info-stnd.texi' || echo '$(srcdir)/'`info-stnd.texi; \ + then \ + rc=0; \ + else \ + rc=$$?; \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +info-stnd.dvi: info-stnd.texi $(srcdir)/version-stnd.texi + $(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \ + `test -f 'info-stnd.texi' || echo '$(srcdir)/'`info-stnd.texi + +info-stnd.pdf: info-stnd.texi $(srcdir)/version-stnd.texi + $(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \ + `test -f 'info-stnd.texi' || echo '$(srcdir)/'`info-stnd.texi + +info-stnd.html: info-stnd.texi $(srcdir)/version-stnd.texi + $(AM_V_MAKEINFO)rm -rf $(@:.html=.htp) + $(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) `test -f 'info-stnd.texi' || echo '$(srcdir)/'`info-stnd.texi; \ + then \ + rm -rf $@ && mv $(@:.html=.htp) $@; \ + else \ + rm -rf $(@:.html=.htp); exit 1; \ + fi +$(srcdir)/version-stnd.texi: $(srcdir)/stamp-1 +$(srcdir)/stamp-1: info-stnd.texi $(top_srcdir)/configure + @(dir=.; test -f ./info-stnd.texi || dir=$(srcdir); \ + set `$(SHELL) $(top_srcdir)/build-aux/mdate-sh $$dir/info-stnd.texi`; \ + echo "@set UPDATED $$1 $$2 $$3"; \ + echo "@set UPDATED-MONTH $$2 $$3"; \ + echo "@set EDITION $(VERSION)"; \ + echo "@set VERSION $(VERSION)") > 1.tmp$$$$ && \ + (cmp -s 1.tmp$$$$ $(srcdir)/version-stnd.texi \ + || (echo "Updating $(srcdir)/version-stnd.texi" && \ + cp 1.tmp$$$$ $(srcdir)/version-stnd.texi.tmp$$$$ && \ + mv $(srcdir)/version-stnd.texi.tmp$$$$ $(srcdir)/version-stnd.texi)) && \ + rm -f 1.tmp$$$$ $(srcdir)/version-stnd.texi.$$$$ + @cp $(srcdir)/version-stnd.texi $@ + +mostlyclean-1: + -rm -f 1.tmp* $(srcdir)/version-stnd.texi.tmp* + +maintainer-clean-1: + -rm -f $(srcdir)/stamp-1 $(srcdir)/version-stnd.texi +.dvi.ps: + $(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) $(AM_V_texinfo) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ + rm -f "$(DESTDIR)$(dvidir)/$$f"; \ + done + +uninstall-html-am: + @$(NORMAL_UNINSTALL) + @list='$(HTMLS)'; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ + rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ + done + +uninstall-info-am: + @$(PRE_UNINSTALL) + @if test -d '$(DESTDIR)$(infodir)' && $(am__can_run_installinfo); then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ + if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ + (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ + echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ + else :; fi); \ + done + +uninstall-pdf-am: + @$(NORMAL_UNINSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ + done + +uninstall-ps-am: + @$(NORMAL_UNINSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ + rm -f "$(DESTDIR)$(psdir)/$$f"; \ + done + +mostlyclean-aminfo: + -rm -rf texinfo.t2d texinfo.t2p info-stnd.t2d info-stnd.t2p + +clean-aminfo: + -test -z "texinfo.dvi texinfo.pdf texinfo.ps texinfo.html info-stnd.dvi \ + info-stnd.pdf info-stnd.ps info-stnd.html" \ + || rm -rf texinfo.dvi texinfo.pdf texinfo.ps texinfo.html info-stnd.dvi \ + info-stnd.pdf info-stnd.ps info-stnd.html + +maintainer-clean-aminfo: + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ + done + +# This directory's subdirectories are mostly independent; you can cd +# into them and run 'make' without going through this Makefile. +# To change the values of 'make' variables: instead of editing Makefiles, +# (1) if the variable is set in 'config.status', edit 'config.status' +# (which will cause the Makefiles to be regenerated when you run 'make'); +# (2) otherwise, pass the desired values on the 'make' command line. +$(am__recursive_targets): + @fail=; \ + if $(am__make_keepgoing); then \ + failcom='fail=yes'; \ + else \ + failcom='exit 1'; \ + fi; \ + dot_seen=no; \ + target=`echo $@ | sed s/-recursive//`; \ + case "$@" in \ + distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \ + *) list='$(SUBDIRS)' ;; \ + esac; \ + for subdir in $$list; do \ + echo "Making $$target in $$subdir"; \ + if test "$$subdir" = "."; then \ + dot_seen=yes; \ + local_target="$$target-am"; \ + else \ + local_target="$$target"; \ + fi; \ + ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ + || eval $$failcom; \ + done; \ + if test "$$dot_seen" = "no"; then \ + $(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \ + fi; test -z "$$fail" + +ID: $(am__tagged_files) + $(am__define_uniq_tagged_files); mkid -fID $$unique +tags: tags-recursive +TAGS: tags + +tags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files) + set x; \ + here=`pwd`; \ + if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \ + include_option=--etags-include; \ + empty_fix=.; \ + else \ + include_option=--include; \ + empty_fix=; \ + fi; \ + list='$(SUBDIRS)'; for subdir in $$list; do \ + if test "$$subdir" = .; then :; else \ + test ! -f $$subdir/TAGS || \ + set "$$@" "$$include_option=$$here/$$subdir/TAGS"; \ + fi; \ + done; \ + $(am__define_uniq_tagged_files); \ + shift; \ + if test -z "$(ETAGS_ARGS)$$*$$unique"; then :; else \ + test -n "$$unique" || unique=$$empty_fix; \ + if test $$# -gt 0; then \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + "$$@" $$unique; \ + else \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + $$unique; \ + fi; \ + fi +ctags: ctags-recursive + +CTAGS: ctags +ctags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files) + $(am__define_uniq_tagged_files); \ + test -z "$(CTAGS_ARGS)$$unique" \ + || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \ + $$unique + +GTAGS: + here=`$(am__cd) $(top_builddir) && pwd` \ + && $(am__cd) $(top_srcdir) \ + && gtags -i $(GTAGS_ARGS) "$$here" +cscopelist: cscopelist-recursive + +cscopelist-am: $(am__tagged_files) + list='$(am__tagged_files)'; \ + case "$(srcdir)" in \ + [\\/]* | ?:[\\/]*) sdir="$(srcdir)" ;; \ + *) sdir=$(subdir)/$(srcdir) ;; \ + esac; \ + for i in $$list; do \ + if test -f "$$i"; then \ + echo "$(subdir)/$$i"; \ + else \ + echo "$$sdir/$$i"; \ + fi; \ + done >> $(top_builddir)/cscope.files + +distclean-tags: + -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags + +distdir: $(BUILT_SOURCES) + $(MAKE) $(AM_MAKEFLAGS) distdir-am + +distdir-am: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done + @list='$(DIST_SUBDIRS)'; for subdir in $$list; do \ + if test "$$subdir" = .; then :; else \ + $(am__make_dryrun) \ + || test -d "$(distdir)/$$subdir" \ + || $(MKDIR_P) "$(distdir)/$$subdir" \ + || exit 1; \ + dir1=$$subdir; dir2="$(distdir)/$$subdir"; \ + $(am__relativize); \ + new_distdir=$$reldir; \ + dir1=$$subdir; dir2="$(top_distdir)"; \ + $(am__relativize); \ + new_top_distdir=$$reldir; \ + echo " (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) top_distdir="$$new_top_distdir" distdir="$$new_distdir" \\"; \ + echo " am__remove_distdir=: am__skip_length_check=: am__skip_mode_fix=: distdir)"; \ + ($(am__cd) $$subdir && \ + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$$new_top_distdir" \ + distdir="$$new_distdir" \ + am__remove_distdir=: \ + am__skip_length_check=: \ + am__skip_mode_fix=: \ + distdir) \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-info +check-am: all-am +check: check-recursive +all-am: Makefile $(INFO_DEPS) +installdirs: installdirs-recursive +installdirs-am: + for dir in "$(DESTDIR)$(infodir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-recursive +install-exec: install-exec-recursive +install-data: install-data-recursive +uninstall: uninstall-recursive + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-recursive +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + -test -z "$(DISTCLEANFILES)" || rm -f $(DISTCLEANFILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +@INSTALL_WARNINGS_FALSE@install-data-local: +clean: clean-recursive + +clean-am: clean-aminfo clean-generic mostlyclean-am + +distclean: distclean-recursive + -rm -f Makefile +distclean-am: clean-am distclean-generic distclean-tags + +dvi: dvi-recursive + +dvi-am: $(DVIS) + +html: html-recursive + +html-am: $(HTMLS) + +info: info-recursive + +info-am: $(INFO_DEPS) + +install-data-am: install-data-local install-info-am + +install-dvi: install-dvi-recursive + +install-dvi-am: $(DVIS) + @$(NORMAL_INSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(dvidir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(dvidir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \ + done +install-exec-am: + +install-html: install-html-recursive + +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + @list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ + $(am__strip_dir) \ + d2=$$d$$p; \ + if test -d "$$d2"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d2'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d2"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \ + else \ + list2="$$list2 $$d2"; \ + fi; \ + done; \ + test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \ + done; } +install-info: install-info-recursive + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(infodir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(infodir)" || exit 1; \ + fi; \ + for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + echo "$$ifile"; \ + else : ; fi; \ + done; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done + @$(POST_INSTALL) + @if $(am__can_run_installinfo); then \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ + install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ + done; \ + else : ; fi +install-man: + +install-pdf: install-pdf-recursive + +install-pdf-am: $(PDFS) + @$(NORMAL_INSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(pdfdir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(pdfdir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done +install-ps: install-ps-recursive + +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(psdir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(psdir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done +installcheck-am: + +maintainer-clean: maintainer-clean-recursive + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-1 \ + maintainer-clean-aminfo maintainer-clean-generic \ + maintainer-clean-vti + +mostlyclean: mostlyclean-recursive + +mostlyclean-am: mostlyclean-1 mostlyclean-aminfo mostlyclean-generic \ + mostlyclean-vti + +pdf: pdf-recursive + +pdf-am: $(PDFS) + +ps: ps-recursive + +ps-am: $(PSS) + +uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.MAKE: $(am__recursive_targets) install-am install-strip + +.PHONY: $(am__recursive_targets) CTAGS GTAGS TAGS all all-am check \ + check-am clean clean-aminfo clean-generic cscopelist-am ctags \ + ctags-am dist-info distclean distclean-generic distclean-tags \ + distdir dvi dvi-am html html-am info info-am install \ + install-am install-data install-data-am install-data-local \ + install-dvi install-dvi-am install-exec install-exec-am \ + install-html install-html-am install-info install-info-am \ + install-man install-pdf install-pdf-am install-ps \ + install-ps-am install-strip installcheck installcheck-am \ + installdirs installdirs-am maintainer-clean maintainer-clean-1 \ + maintainer-clean-aminfo maintainer-clean-generic \ + maintainer-clean-vti mostlyclean mostlyclean-1 \ + mostlyclean-aminfo mostlyclean-generic mostlyclean-vti pdf \ + pdf-am ps ps-am tags tags-am uninstall uninstall-am \ + uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.PRECIOUS: Makefile + + +@INSTALL_WARNINGS_TRUE@install-data-local: +@INSTALL_WARNINGS_TRUE@ @echo +@INSTALL_WARNINGS_TRUE@ @echo "WARNING: If your texmf tree does not already contain" +@INSTALL_WARNINGS_TRUE@ @echo " up-to-date versions, you must install" +@INSTALL_WARNINGS_TRUE@ @echo " texinfo.tex and txi-??.tex manually," +@INSTALL_WARNINGS_TRUE@ @echo " perhaps in TEXMF/tex/texinfo/," +@INSTALL_WARNINGS_TRUE@ @echo " where TEXMF is a root of your TeX tree." +@INSTALL_WARNINGS_TRUE@ @echo " See doc/README for some considerations." +@INSTALL_WARNINGS_TRUE@ @echo " You can run make TEXMF=/your/texmf install-tex to do this." +@INSTALL_WARNINGS_TRUE@ @echo +@INSTALL_WARNINGS_TRUE@ @echo " You may also need to install epsf.tex in" +@INSTALL_WARNINGS_TRUE@ @echo " TEXMF/tex/generic/dvips, if your TeX" +@INSTALL_WARNINGS_TRUE@ @echo " installation did not include it." +install-tex: + test -n "$(TEXMF)" || (echo "TEXMF must be set." >&2; exit 1) + $(mkinstalldirs) $(DESTDIR)$(texmf_texinfo) $(DESTDIR)$(texmf_dvips) + $(INSTALL_DATA) $(srcdir)/texinfo.tex $(DESTDIR)$(texmf_texinfo)/texinfo.tex + $(INSTALL_DATA) $(srcdir)/epsf.tex $(DESTDIR)$(texmf_dvips)/epsf.tex + for f in $(TXI_XLATE); do \ + $(INSTALL_DATA) $(srcdir)/$$f $(DESTDIR)$(texmf_texinfo)/$$f; done + +# Do not create info files for distribution. +dist-info: +# +wwwdoc-build: + rm -rf $(doctemp) && mkdir $(doctemp) + cd $(doctemp) \ + && ln -s ../*.texi . \ + && $(gendocs_invoke) -o $(manual1) $(manual1) $(manual1_title) \ + && $(gendocs_invoke) -o $(manual2) $(manual2) $(manual2_title) \ + && pod2html $(pod2texi_pl) >pod2texi.html \ + && echo "Manuals ready for web distribution under: $(doctemp)/" +# +# At official release, we need to update: +# http://www.gnu.org/software/texinfo/manual/ +wwwdoc-install: + cp -arf $(doctemp)/$(manual1) $(doctemp)/$(manual2) \ + $(doctemp)/pod2texi.html \ + $(www_target) + ls -ltu $(www_target)/*/html_node | tail # cvs rm -f obsolete files +# followed by cvs add of new files and cvs commit. + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/macros/texinfo/texinfo/doc/README b/macros/texinfo/texinfo/doc/README new file mode 100644 index 0000000000..e786c503ca --- /dev/null +++ b/macros/texinfo/texinfo/doc/README @@ -0,0 +1,35 @@ +texinfo/doc/README + + Copyright 2002-2019 Free Software Foundation, Inc. + + Copying and distribution of this file, with or without modification, + are permitted in any medium without royalty provided the copyright + notice and this notice are preserved. + +This directory contains documentation on the Texinfo system and the TeX +sources needed to process Texinfo sources. We recommend using the +texi2dvi included in this distribution to run a Texinfo manual through +TeX to produce a DVI file. + +The .tex files are not installed automatically because TeX installations +vary so widely. Installing them in the wrong place would give a false +sense of security. So, you should simply cp *.tex to the appropriate +place. If your installation follows the TeX Directory Structure +standard (http://tug.org/tds/), this will be the directory +TEXMF/tex/texinfo/ for texinfo.tex, and TEXMF/tex/generic/epsf/ for +epsf.tex. + +It is also possible to put these .tex files in a `local' place instead +of overwriting existing ones, but this is more complicated. See your TeX +documentation in general and the texmf.cnf file in particular for information. + +If you add files to your TeX installations, not just replace existing +ones, you very likely have to update your ls-R file; do this by +running the mktexlsr command. + +You can get the latest texinfo.tex from +ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex (and all GNU mirrors) +ftp://tug.org/tex/texinfo.tex (and all CTAN mirrors) +or from the gnulib project on Savannah (among other places). +If you have problems with the texinfo.tex in this distribution, please check +for a newer version. diff --git a/macros/texinfo/texinfo/doc/epsf.tex b/macros/texinfo/texinfo/doc/epsf.tex new file mode 100644 index 0000000000..847de77fb6 --- /dev/null +++ b/macros/texinfo/texinfo/doc/epsf.tex @@ -0,0 +1,653 @@ +%%% -*-TeX-*- +%%% ==================================================================== +%%% @TeX-file{ +%%% author = "Tom Rokicki", +%%% version = "2.7.4", +%%% date = "14 February 2011", +%%% time = "15:44:06 MST", +%%% filename = "epsf.tex", +%%% address = "Tom Rokicki +%%% Box 2081 +%%% Stanford, CA 94309 +%%% USA", +%%% telephone = "+1 415 855 9989", +%%% checksum = "29223 653 3100 27123", +%%% email = "rokicki@cs.stanford.edu (Internet)", +%%% codetable = "ISO/ASCII", +%%% copyright = "This file is freely redistributable and +%%% placed into the public domain by Tomas +%%% Rokicki.", +%%% keywords = "PostScript, TeX", +%%% license = "public domain", +%%% supported = "yes", +%%% abstract = "This file contains macros to support the +%%% inclusion of Encapsulated PostScript files +%%% in TeX documents.", +%%% docstring = "This file contains TeX macros to include an +%%% Encapsulated PostScript graphic. It works +%%% by finding the bounding box comment, +%%% calculating the correct scale values, and +%%% inserting a vbox of the appropriate size at +%%% the current position in the TeX document. +%%% +%%% To use, simply use +%%% +%%% \input epsf % somewhere early on in your TeX file +%%% +%%% % then where you want to insert a vbox for a figure: +%%% \epsfbox{filename.ps} +%%% +%%% Alternatively, you can supply your own +%%% bounding box by +%%% +%%% \epsfbox[0 0 30 50]{filename.ps} +%%% +%%% This will not read in the file, and will +%%% instead use the bounding box you specify. +%%% +%%% The effect will be to typeset the figure as +%%% a TeX box, at the point of your \epsfbox +%%% command. By default, the graphic will have +%%% its `natural' width (namely the width of +%%% its bounding box, as described in +%%% filename.ps). The TeX box will have depth +%%% zero. +%%% +%%% You can enlarge or reduce the figure by +%%% using +%%% +%%% \epsfxsize = <dimen> \epsfbox{filename.ps} +%%% or +%%% \epsfysize = <dimen> \epsfbox{filename.ps} +%%% +%%% instead. Then the width of the TeX box will +%%% be \epsfxsize and its height will be scaled +%%% proportionately (or the height will be +%%% \epsfysize and its width will be scaled +%%% proportionately). +%%% +%%% The width (and height) is restored to zero +%%% after each use, so \epsfxsize or \epsfysize +%%% must be specified before EACH use of +%%% \epsfbox. +%%% +%%% A more general facility for sizing is +%%% available by defining the \epsfsize macro. +%%% Normally you can redefine this macro to do +%%% almost anything. The first parameter is +%%% the natural x size of the PostScript +%%% graphic, the second parameter is the +%%% natural y size of the PostScript graphic. +%%% It must return the xsize to use, or 0 if +%%% natural scaling is to be used. Common uses +%%% include: +%%% +%%% \epsfxsize % just leave the old value alone +%%% 0pt % use the natural sizes +%%% #1 % use the natural sizes +%%% \hsize % scale to full width +%%% 0.5#1 % scale to 50% of natural size +%%% \ifnum #1 > \hsize \hsize \else #1\fi +%%% % smaller of natural, hsize +%%% +%%% If you want TeX to report the size of the +%%% figure (as a message on your terminal when +%%% it processes each figure), use +%%% `\epsfverbosetrue'. +%%% +%%% If you only want to get the bounding box +%%% extents, without producing any output boxes +%%% or \special{}, then use \epsfgetbb{filename}. +%%% The bounding box corner coordinates are saved +%%% in the macros \epsfllx, \epsflly, \epsfurx, +%%% and \epsfury in PostScript units of big +%%% points. +%%% +%%% Revision history: +%%% +%%% --------------------------------------------- +%%% epsf.tex macro file: +%%% Originally written by Tomas Rokicki of +%%% Radical Eye Software, 29 Mar 1989. +%%% +%%% --------------------------------------------- +%%% Revised by Don Knuth, 3 Jan 1990. +%%% +%%% --------------------------------------------- +%%% Revised by Tomas Rokicki, 18 Jul 1990. +%%% Accept bounding boxes with no space after +%%% the colon. +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% <beebe@math.utah.edu>, 03 Dec 1991 [2.0]. +%%% Add version number and date typeout. +%%% +%%% Use \immediate\write16 instead of \message +%%% to ensure output on new line. +%%% +%%% Handle nested EPS files. +%%% +%%% Handle %%BoundingBox: (atend) lines. +%%% +%%% Do not quit when blank lines are found. +%%% +%%% Add a few percents to remove generation of +%%% spurious blank space. +%%% +%%% Move \special output to +%%% \epsfspecial{filename} so that other macro +%%% packages can input this one, then change +%%% the definition of \epsfspecial to match +%%% another DVI driver. +%%% +%%% Move size computation to \epsfsetsize which +%%% can be called by the user; the verbose +%%% output of the bounding box and scaled width +%%% and height happens here. +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% <beebe@math.utah.edu>, 05 May 1992 [2.1]. +%%% Wrap \leavevmode\hbox{} around \vbox{} with +%%% the \special so that \epsffile{} can be +%%% used inside \begin{center}...\end{center} +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% <beebe@math.utah.edu>, 09 Dec 1992 [2.2]. +%%% Introduce \epsfshow{true,false} and +%%% \epsfframe{true,false} macros; the latter +%%% suppresses the insertion of the PostScript, +%%% and instead just creates an empty box, +%%% which may be handy for rapid prototyping. +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% <beebe@math.utah.edu>, 14 Dec 1992 [2.3]. +%%% Add \epsfshowfilename{true,false}. When +%%% true, and \epsfshowfalse is specified, the +%%% PostScript file name will be displayed +%%% centered in the figure box. +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% <beebe@math.utah.edu>, 20 June 1993 [2.4]. +%%% Remove non-zero debug setting of \epsfframemargin, +%%% and change margin handling to preserve EPS image +%%% size and aspect ratio, so that the actual +%%% box is \epsfxsize+\epsfframemargin wide by +%%% \epsfysize+\epsfframemargin high. +%%% Reduce output of \epsfshowfilenametrue to +%%% just the bare file name. +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% <beebe@math.utah.edu>, 13 July 1993 [2.5]. +%%% Add \epsfframethickness for control of +%%% \epsfframe frame lines. +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% <beebe@math.utah.edu>, 02 July 1996 [2.6] +%%% Add missing initialization \epsfatendfalse; +%%% the lack of this resulted in the wrong +%%% BoundingBox being picked up, mea culpa, sigh... +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% <beebe@math.utah.edu>, 25 October 1996 [2.7] +%%% Update to match changes in from dvips 5-600 +%%% distribution: new user-accessible macros: +%%% \epsfclipon, \epsfclipoff, \epsfdrafton, +%%% \epsfdraftoff, change \empty to \epsfempty. +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% <beebe@math.utah.edu>, 18 May 2002 [2.7.1] +%%% Add write statements to echo input file +%%% names. Prior to that change, an error in +%%% such a file could be quite hard to track +%%% down: a long list of TeX page numbers could +%%% suddenly be followed by ``TeX buffer +%%% capacity'' exceeded, without any indication +%%% of the file that was responsible. +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% <beebe@math.utah.edu>, 16 May 2003 [2.7.2] +%%% Supply two critical percent characters that +%%% were mistakenly omitted in version 2.7.1, +%%% and resulted in a small amount of spurious +%%% horizontal space. +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% <beebe@math.utah.edu>, 14 Feb 2011 [2.7.3] +%%% Add previously-missing \space in rwi +%%% assignments (bug reported 14-Feb-2011 by +%%% Stefan Rueger <s.rueger@open.ac.uk>). +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% <beebe@math.utah.edu>, Karl Berry +%%% <karl@freefriends.org>, and Robin Fairbairns +%%% <Robin.Fairbairns@cl.cam.ac.uk>, +%%% 23 July 2005 [2.7.3] +%%% Add critical \hbox{} wrapper in \epsfsetgraph +%%% so that \epsfbox{} does not conflict with +%%% LaTeX center environment when \epsfbox{} is +%%% surrounded by other horizonal objects. +%%% Improve macro readability by adding legal, +%%% but invisible-in-typeset-output, spaces. +%%% Ensure that verbose status reports come +%%% inside (filename ...) list. +%%% +%%% --------------------------------------------- +%%% The checksum field above contains a CRC-16 +%%% checksum as the first value, followed by +%%% the equivalent of the standard UNIX wc +%%% (word count) utility output of lines, +%%% words, and characters. This is produced by +%%% Robert Solovay's checksum utility.", +%%% } +%%% ==================================================================== + +%\immediate \write16 {This is `epsf.tex' v2.0 <02 Dec 1991>}% +%\immediate \write16 {This is `epsf.tex' v2.1 <05 May 1992>}% +%\immediate \write16 {This is `epsf.tex' v2.2 <09 Dec 1992>}% +%\immediate \write16 {This is `epsf.tex' v2.3 <14 Dec 1992>}% +%\immediate \write16 {This is `epsf.tex' v2.4 <20 June 1993>}% +%\immediate \write16 {This is `epsf.tex' v2.5 <13 July 1993>}% +%\immediate \write16 {This is `epsf.tex' v2.6 <02 July 1996>}% +%\immediate \write16 {This is `epsf.tex' v2.7 <25 October 1996>}% +%\immediate \write16 {This is `epsf.tex' v2.7.1 <18 May 2002>}% +%\immediate \write16 {This is `epsf.tex' v2.7.2 <16 May 2003>}% +%\immediate \write16 {This is `epsf.tex' v2.7.3 <23 July 2005>}% +\immediate \write16 {This is `epsf.tex' v2.7.4 <14 February 2011>}% +% +\newread \epsffilein % file to \read +\newif \ifepsfatend % need to scan to LAST %%BoundingBox comment? +\newif \ifepsfbbfound % success? +\newif \ifepsfdraft % use draft mode? +\newif \ifepsffileok % continue looking for the bounding box? +\newif \ifepsfframe % frame the bounding box? +\newif \ifepsfshow % show PostScript file, or just bounding box? +\epsfshowtrue % default is to display PostScript file +\newif \ifepsfshowfilename % show the file name if \epsfshowfalse specified? +\newif \ifepsfverbose % report what you're making? +\newdimen \epsfframemargin % margin between box and frame +\newdimen \epsfframethickness % thickness of frame rules +\newdimen \epsfrsize % vertical size before scaling +\newdimen \epsftmp % register for arithmetic manipulation +\newdimen \epsftsize % horizontal size before scaling +\newdimen \epsfxsize % horizontal size after scaling +\newdimen \epsfysize % vertical size after scaling +\newdimen \pspoints % conversion factor +% +\pspoints = 1bp % Adobe points are `big' +\epsfxsize = 0pt % default value, means `use natural size' +\epsfysize = 0pt % ditto +\epsfframemargin = 0pt % default value: frame box flush around picture +\epsfframethickness = 0.4pt % TeX's default rule thickness +% +\def \epsfbox #1{% + \global \def \epsfllx {72}% + \global \def \epsflly {72}% + \global \def \epsfurx {540}% + \global \def \epsfury {720}% + \def \lbracket {[}% + \def \testit {#1}% + \ifx \testit \lbracket + \let \next = \epsfgetlitbb + \else + \let \next = \epsfnormal + \fi + \next{#1}% +}% +% +% We use \epsfgetlitbb if the user specified an explicit bounding box, +% and \epsfnormal otherwise. Because \epsfgetbb can be called +% separately to retrieve the bounding box, we move the verbose +% printing the bounding box extents and size on the terminal to +% \epsfstatus. Therefore, when the user provided the bounding box, +% \epsfgetbb will not be called, so we must call \epsfsetsize and +% \epsfstatus ourselves. +% +\def \epsfgetlitbb #1#2 #3 #4 #5]#6{% + \epsfgrab #2 #3 #4 #5 .\\% + \epsfsetsize + \epsfstatus{#6}% + \epsfsetgraph{#6}% +}% +% +\def \epsfnormal #1{% + \epsfgetbb{#1}% + \epsfsetgraph{#1}% +}% +% +\def \epsfgetbb #1{% +% +% The first thing we need to do is to open the +% PostScript file, if possible. +% + \openin\epsffilein=#1 + \immediate \write16 {(#1}% + \ifeof \epsffilein + \errmessage{Could not open file #1, ignoring it}% + \else %process the file + {% %start a group to contain catcode changes + % Make all special characters, except space, to be of type + % `other' so we process the file in almost verbatim mode + % (TeXbook, p. 344). + \chardef \other = 12% + \def \do ##1{\catcode`##1=\other}% + \dospecials + \catcode `\ = 10% + \epsffileoktrue %true while we are looping + \epsfatendfalse %[02-Jul-1996]: add forgotten initialization + \loop %reading lines from the EPS file + \read \epsffilein to \epsffileline + \ifeof \epsffilein %then no more input + \epsffileokfalse %so set completion flag + \else %otherwise process one line + \expandafter \epsfaux \epsffileline :. \\% + \fi + \ifepsffileok + \repeat + \ifepsfbbfound + \else + \ifepsfverbose + \immediate \write16 {No BoundingBox comment found in % + file #1; using defaults}% + \fi + \fi + }% %end catcode changes + \closein\epsffilein + \fi %end of file processing + \epsfsetsize %compute size parameters + \epsfstatus{#1}% + \immediate \write16 {)}% +}% +% +% Clipping control: +\def \epsfclipon {\def \epsfclipstring { clip}}% +\def \epsfclipoff {\def \epsfclipstring {\ifepsfdraft \space clip\fi}}% +\epsfclipoff % default for dvips is OFF +% +% The special that is emitted by \epsfsetgraph comes from this macro. +% It is defined separately to allow easy customization by other +% packages that first \input epsf.tex, then redefine \epsfspecial. +% This macro is invoked in the lower-left corner of a box of the +% width and height determined from the arguments to \epsffile, or +% from the %%BoundingBox in the EPS file itself. +% +% This version is for dvips: +\def \epsfspecial #1{% + \epsftmp=10\epsfxsize + \divide \epsftmp by \pspoints + \ifnum \epsfrsize = 0% + \relax + \special{PSfile=\ifepsfdraft psdraft.ps\else#1\fi\space + llx=\epsfllx\space + lly=\epsflly\space + urx=\epsfurx\space + ury=\epsfury\space + rwi=\number\epsftmp\space + \epsfclipstring + }% + \else + \epsfrsize=10\epsfysize + \divide \epsfrsize by \pspoints + \special{PSfile=\ifepsfdraft psdraft.ps\else#1\fi\space + llx=\epsfllx\space + lly=\epsflly\space + urx=\epsfurx\space + ury=\epsfury\space + rwi=\number\epsftmp\space + rhi=\number\epsfrsize + \epsfclipstring + }% + \fi +}% +% +% \epsfframe macro adapted from the TeXbook, exercise 21.3, p. 223, 331. +% but modified to set the box width to the natural width, rather +% than the line width, and to include space for margins and rules +\def \epsfframe #1% +{% + % method for detecting latex suggested by Robin Fairbairns, May 2005. + \ifx \documentstyle \epsfundefined + \relax + \else +% \leavevmode % so we can put this inside + % a latex centered environment + % The \leavevmode breaks under plain when this is inside a box, + % because it forces the figure to be the entire \hsize. On the + % other hand, we need the \leavevmode for it to work in LaTeX, + % because the {center} environment works by adjusting TeX's + % paragraph parameters. + % + % Compare the LaTeX sequence + % \begin{center} + % \epsfbox{tip.eps}q + % \end{center} + % (needs the \leavevmode to put the q right next to the image) + % + % with the plain TeX sequence: + % \leftline{\vbox{\epsfbox{tip.eps}}q} + % (had the q all the way over to the right, when \leavevmode was used) + \fi + % + \setbox0 = \hbox{#1}% + \dimen0 = \wd0 % natural width of argument + \advance \dimen0 by 2\epsfframemargin % plus width of 2 margins + \advance \dimen0 by 2\epsfframethickness % plus width of 2 rule lines + \relax + \hbox{% + \vbox + {% + \hrule height \epsfframethickness depth 0pt + \hbox to \dimen0 + {% + \hss + \vrule width \epsfframethickness + \kern \epsfframemargin + \vbox {\kern \epsfframemargin \box0 \kern \epsfframemargin }% + \kern \epsfframemargin + \vrule width \epsfframethickness + \hss + }% end hbox + \hrule height 0pt depth \epsfframethickness + }% end vbox + }% end hbox + \relax +}% +% +\def \epsfsetgraph #1% +{% + % + % Make the vbox and stick in a \special that the DVI driver can + % parse. \vfil and \hfil are used to place the \special origin at + % the lower-left corner of the vbox. \epsfspecial can be redefined + % to produce alternate \special syntaxes. + % + \ifvmode \leavevmode \fi + \relax + \hbox{% so we can put this in \begin{center}...\end{center} + \ifepsfframe \expandafter \epsfframe \fi + {\vbox to\epsfysize + {% + \ifepsfshow + % output \special{} at lower-left corner of figure box + \vfil + \hbox to \epsfxsize{\epsfspecial{#1}\hfil}% + \else + \vfil + \hbox to\epsfxsize{% + \hss + \ifepsfshowfilename + {% + \epsfframemargin=3pt % local change of margin + \epsfframe{{\tt #1}}% + }% + \fi + \hss + }% + \vfil + \fi + }% + }}% + \relax + % + % Reset \epsfxsize and \epsfysize, as documented above. + % + \global \epsfxsize = 0pt + \global \epsfysize = 0pt +}% +% +% Now we have to calculate the scale and offset values to use. +% First we compute the natural sizes. +% +\def \epsfsetsize +{% + \epsfrsize = \epsfury \pspoints + \advance \epsfrsize by -\epsflly \pspoints + \epsftsize = \epsfurx \pspoints + \advance \epsftsize by -\epsfllx \pspoints +% +% If `epsfxsize' is 0, we default to the natural size of the picture. +% Otherwise we scale the graph to be \epsfxsize wide. +% + \epsfxsize = \epsfsize{\epsftsize}{\epsfrsize}% + \ifnum \epsfxsize = 0 + \ifnum \epsfysize = 0 + \epsfxsize = \epsftsize + \epsfysize = \epsfrsize + \epsfrsize = 0pt +% +% We have a sticky problem here: TeX doesn't do floating point arithmetic! +% Our goal is to compute y = rx/t. The following loop does this reasonably +% fast, with an error of at most about 16 sp (about 1/4000 pt). +% + \else + \epsftmp = \epsftsize + \divide \epsftmp by \epsfrsize + \epsfxsize = \epsfysize + \multiply \epsfxsize by \epsftmp + \multiply \epsftmp by \epsfrsize + \advance \epsftsize by -\epsftmp + \epsftmp = \epsfysize + \loop + \advance \epsftsize by \epsftsize + \divide \epsftmp by 2 + \ifnum \epsftmp > 0 + \ifnum \epsftsize < \epsfrsize + \else + \advance \epsftsize -\epsfrsize + \advance \epsfxsize \epsftmp + \fi + \repeat + \epsfrsize = 0pt + \fi + \else + \ifnum \epsfysize = 0 + \epsftmp = \epsfrsize + \divide \epsftmp by \epsftsize + \epsfysize = \epsfxsize + \multiply \epsfysize by \epsftmp + \multiply \epsftmp by \epsftsize + \advance \epsfrsize by -\epsftmp + \epsftmp = \epsfxsize + \loop + \advance \epsfrsize by \epsfrsize + \divide \epsftmp by 2 + \ifnum \epsftmp > 0 + \ifnum \epsfrsize < \epsftsize + \else + \advance \epsfrsize by -\epsftsize + \advance \epsfysize by \epsftmp + \fi + \repeat + \epsfrsize = 0pt + \else + \epsfrsize = \epsfysize + \fi + \fi +}% +% +% Issue some status messages if the user requested them +% +\def \epsfstatus #1{% arg = filename + \ifepsfverbose + \immediate \write16 {#1: BoundingBox: + llx = \epsfllx \space lly = \epsflly \space + urx = \epsfurx \space ury = \epsfury \space}% + \immediate \write16 {#1: scaled width = \the\epsfxsize \space + scaled height = \the\epsfysize}% + \fi +}% +% +% We still need to define the tricky \epsfaux macro. This requires +% a couple of magic constants for comparison purposes. +% +{\catcode`\%=12 \global \let \epsfpercent=%\global \def \epsfbblit {%BoundingBox}}% +\global \def \epsfatend{(atend)}% +% +% So we're ready to check for `%BoundingBox:' and to grab the +% values if they are found. +% +% If we find a line +% +% %%BoundingBox: (atend) +% +% then we ignore it, but set a flag to force parsing all of the +% file, so the last %%BoundingBox parsed will be the one used. This +% is necessary, because EPS files can themselves contain other EPS +% files with their own %%BoundingBox comments. +% +% If we find a line +% +% %%BoundingBox: llx lly urx ury +% +% then we save the 4 values in \epsfllx, \epsflly, \epsfurx, \epsfury. +% Then, if we have not previously parsed an (atend), we flag completion +% and can stop reading the file. Otherwise, we must keep on reading +% to end of file so that we find the values on the LAST %%BoundingBox. +\long \def \epsfaux#1#2:#3\\% +{% + \def \testit {#2}% % save second character up to just before colon + \ifx#1\epsfpercent % then first char is percent (quick test) + \ifx \testit \epsfbblit % then (slow test) we have %%BoundingBox + \epsfgrab #3 . . . \\% + \ifx \epsfllx\epsfatend % then ignore %%BoundingBox: (atend) + \global \epsfatendtrue + \else % else found %%BoundingBox: llx lly urx ury + \ifepsfatend % then keep parsing ALL %%BoundingBox lines + \else % else stop after first one parsed + \epsffileokfalse + \fi + \global \epsfbbfoundtrue + \fi + \fi + \fi +}% +% +% Here we grab the values and stuff them in the appropriate definitions. +% +\def \epsfempty {}% +\def \epsfgrab #1 #2 #3 #4 #5\\{% + \global \def \epsfllx {#1}\ifx \epsfllx\epsfempty + \epsfgrab #2 #3 #4 #5 .\\\else + \global \def \epsflly {#2}% + \global \def \epsfurx {#3}\global \def \epsfury {#4}\fi +}% +% +% We default the epsfsize macro. +% +\def \epsfsize #1#2{\epsfxsize}% +% +% Finally, another definition for compatibility with older macros. +% +\let \epsffile = \epsfbox +\endinput diff --git a/macros/texinfo/texinfo/doc/fdl.texi b/macros/texinfo/texinfo/doc/fdl.texi new file mode 100644 index 0000000000..542edaad25 --- /dev/null +++ b/macros/texinfo/texinfo/doc/fdl.texi @@ -0,0 +1,505 @@ +@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{https://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 +ASCII without markup, Texinfo input format, La@TeX{} input +format, SGML or XML using a publicly available +DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples +of transparent image formats include PNG, XCF and +JPG@. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, SGML or +XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML, +PostScript or 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{https://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: diff --git a/macros/texinfo/texinfo/doc/info-stnd.texi b/macros/texinfo/texinfo/doc/info-stnd.texi new file mode 100644 index 0000000000..86c92e867e --- /dev/null +++ b/macros/texinfo/texinfo/doc/info-stnd.texi @@ -0,0 +1,2554 @@ +\input texinfo.tex @c -*-texinfo-*- +@c We must \input texinfo.tex instead of texinfo, otherwise make +@c distcheck in the Texinfo distribution fails, because the texinfo Info +@c file is made first, and texi2dvi must include . first in the path. +@comment %**start of header +@setfilename info-stnd.info +@include version-stnd.texi +@settitle Stand-alone GNU Info @value{VERSION} +@syncodeindex vr cp +@syncodeindex fn cp +@syncodeindex ky cp +@comment %**end of header + +@copying +This manual is for Stand-alone GNU Info (version @value{VERSION}, +@value{UPDATED}), a program for viewing documents in Info format +(usually created from Texinfo source files). + +Copyright @copyright{} 1992, 1993, 1996, 1997, 1998, 1999, 2001, +2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, +2013, 2014, 2015, 2016, 2017, 2018, 2019 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, with the Front-Cover Texts being ``A GNU Manual'', +and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Texinfo manual. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to +copy and modify this GNU manual. Buying copies from the FSF +supports it in developing GNU and promoting software freedom.'' +@end quotation + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end copying + +@dircategory Texinfo documentation system +@direntry +* info stand-alone: (info-stnd). Read Info documents without Emacs. +@end direntry + +@titlepage +@title Stand-alone GNU Info +@subtitle for version @value{VERSION}, @value{UPDATED} +@author Brian J. Fox +@author and Texinfo maintainers +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Stand-alone GNU Info + +This documentation describes the stand-alone Info reader which you can +use to read Info documentation. + +If you are new to the Info reader, then you can get started by typing +@samp{H} for a list of basic key bindings. You can read through the +rest of this manual by typing @key{SPC} and @key{DEL} (or @key{Space} +and @key{Backspace}) to move forwards and backwards in it. + +@end ifnottex + +@menu +* Stand-alone Info:: What is Info? +* Invoking Info:: Options you can pass on the command line. +* Cursor Commands:: Commands which move the cursor within a node. +* Scrolling Commands:: Commands for reading the text within a node. +* Node Commands:: Commands for selecting a new node. +* Searching Commands:: Commands for searching an Info file. +* Index Commands:: Commands for looking up in indices. +* Xref Commands:: Commands for selecting cross-references. +* Window Commands:: Commands which manipulate multiple windows. +* Printing Nodes:: How to print out the contents of a node. +* Miscellaneous Commands:: A few commands that defy categorization. +* Variables:: How to change the default behavior of Info. +* Colors and Styles:: Customize the colors used by Info. +* Custom Key Bindings:: How to define your own key-to-command bindings. +* Index:: Global index. +@end menu + + +@node Stand-alone Info +@chapter Stand-alone Info + +The @dfn{Info} program described here is a stand-alone program, part +of the Texinfo distribution, which is used to view Info files on a +text terminal. @dfn{Info files} are typically the result of +processing Texinfo files with the program @code{makeinfo} (also in the +Texinfo distribution). + +Texinfo itself (@pxref{Top,,, texinfo, Texinfo}) is a documentation +system that uses a single source file to produce both on-line +information and printed output. You can typeset and print the files +that you read in Info. + +@cindex Emacs Info reader +@cindex Info files, reading in Emacs +GNU Emacs also provides an Info reader (just type @kbd{M-x info} in +Emacs). Emacs Info and stand-alone Info have nearly identical user +interfaces, although customization and other details are different +(this manual explains the stand-alone Info reader). The Emacs Info +reader supports the X Window System and other such bitmapped +interfaces, not just plain ASCII, so if you want a prettier display +for Info files, you should try it. You can use Emacs Info without +using Emacs for anything else. (Type @kbd{C-x C-c} to exit; this also +works in the stand-alone Info reader.) @xref{Top,,, info, Info} for a +tutorial and more background information about the Info system, as well +as information about the Info reader that is part of GNU Emacs, + +@cindex bugs, reporting +Please report bugs in this stand-alone Info program to +@email{bug-texinfo@@gnu.org}. Bugs in the Emacs Info reader should be +sent to @email{bug-gnu-emacs@@gnu.org}. + + +@node Invoking Info +@chapter Invoking Info + +@cindex Info, invoking +@cindex invoking Info +@cindex command line options +@cindex options, command line +@cindex arguments, command line + +GNU Info accepts several options to control the initial node or nodes +being viewed, and to specify which directories to search for Info files. +Here is a template showing an invocation of GNU Info from the shell: + +@example +info [@var{option}@dots{}] [@var{manual}] [@var{menu-or-index-item}@dots{}] +@end example + +Info will look for an entry called @var{manual} in the directory +files, which are named @file{dir}, that it finds in its search path. +The search is case-insensitive and considers substrings. +(If @var{manual} is not given, by default Info displays a composite +directory listing, constructed by combining the @file{dir} files.) +A basic example: + +@example +info coreutils +@end example + +This looks for an entry labelled @code{coreutils}, or +@code{Coreutils}, etc., and if found, displays the referenced file +(e.g., @file{coreutils.info}) at the location given. +@code{info coreu} will find it too, if there is no better match. + +Another example: + +@example +info ls +@end example + +Assuming the normal @code{dir} entry for @code{ls}, this will show the +@code{ls} documentation, which happens to be within the +@code{coreutils} manual rather than a separate manual. The @code{dir} +entries can point to an any node within a manual, so that users don't +have to be concerned with the exact structure used by different +authors. + +@cindex compressed Info files +@cindex files, compressed +@cindex Info files, compressed +If no entry is found in the directories, Info looks for files in its +search path with names based on @var{manual}. If @var{manual} is +not found, Info looks for it with a number of known extensions of Info +files, namely @file{.info}, @file{-info}, @file{/index}, and @file{.inf}. +For every known extension, if a regular file is not found, Info looks +for a compressed file. Info supports files compressed with @code{gzip}, +@code{xz}, @code{bzip2}, @code{lzip}, @code{lzma}, @code{compress} and +@code{yabba} programs, assumed to have extensions @file{.z}, @file{.gz}, +@file{.xz}, @file{.bz2}, @file{.lz}, @file{.lzma}, @file{.Z}, and +@file{.Y} respectively.@footnote{On MS-DOS, Info allows for the Info +extension, such as @code{.inf}, and the short compressed file extensions, +such as @file{.z} and @file{.gz}, to be merged into a single extension, +since DOS doesn't allow more than a single dot in the basename of +a file. Thus, on MS-DOS, if Info looks for @file{bison}, file names +like @file{bison.igz} and @file{bison.inz} will be found and decompressed +by @code{gunzip}.} + +You can specify the name of a node to visit with the @code{--node} or +@code{-n} option. Alternatively, you can specify the file and node +together using the same format that occurs in Info cross-references. +These two examples both load the @samp{Files} node within the +@samp{emacs} manual: + +@example +info emacs -n Files +info '(emacs)Files' +@end example + +@cindex absolute Info file names +@cindex relative Info file names +@cindex file names, relative +@cindex Info files, relative +If you want to load a file without looking in the search path, specify +@var{manual} either as an absolute path, or as a path relative to the +current directory which contains at least one slash character. (You +can also use the @code{--file} option for similar behavior, described +below.) +Examples: + +@example +info /usr/local/share/info/bash.info +info ./document.info +@end example + +@noindent +Info looks for @var{manual} only in the explicitly specified +directory, and adds that directory to its search path. + +@anchor{command-line menu items} +@cindex menu, following +Info treats any remaining arguments as the names of menu items, or +(see below) index entries. The first argument is a menu item in the +@samp{Top} node of the file loaded, the second argument is a menu item +in the first argument's node, etc. You can move to the node of your +choice by specifying the menu names which describe the path to that +node. For example, + +@example +info emacs buffers +info texinfo Overview 'Using Texinfo' +@end example + +@noindent +The first example selects the menu item @samp{Buffers} in the node +@samp{(emacs)Top}. The second example loads the @file{texinfo} file and +looks in its top-level menu for a @samp{Overview} item, looks in the menu +of the node referenced, and finally displays the node referenced by the +@samp{Using Texinfo} item. + +If there was only one @var{menu-or-index-item} argument and it wasn't +found as a menu item, Info looks for it as an index entry. For example: + +@example +info libc printf +@end example + +@noindent +This loads the libc Info manual and first looks for @code{printf} in +the top-level menu as usual; since it isn't there (at this writing), +it then looks in the indices. If it's found there (which it is), +the relevant node at the given location is displayed. + +A complete list of options follows. + +@table @code +@anchor{--all} +@item --all +@itemx -a +@cindex @code{--all} (@code{-a}) command line option +Find all files matching @var{manual}. Three usage patterns are +supported, as follows. + +First, if @code{--all} is used together with @option{--where}, +@command{info} prints the names of all matching files found on +standard output (including @samp{*manpages*} if relevant) and exits. + +Second, if @code{--all} is used together with @option{--output}, the +contents of all matched files are dumped to the specified output +file. + +Otherwise, an interactive session is initiated. If more than one file +matches, a menu node is displayed listing the matches and allowing you +to select one. This menu node can be brought back at any time by +pressing @kbd{C-x f}. If there is only one match, @command{info} +starts as usual. + +When used with the @option{--index-search} option, @command{info} +displays a menu of matching index entries (just as the +@code{virtual-index} command does; see @ref{Index Commands}). + +The @option{--node} option cannot be used together with this option. + +@anchor{--apropos} +@item --apropos=@var{string} +@itemx -k @var{string} +@cindex @code{--apropos} (@code{-k}) command line option +@cindex Searching all indices +@cindex Info files@r{, searching all indices} +@cindex Apropos@r{, in Info files} +Specify a string to search in every index of every Info file installed +on your system. Info looks up the named @var{string} in all the +indices it can find, prints the results to standard output, and then +exits. If you are not sure which Info file explains certain issues, +this option is your friend. (If your system has a lot of Info files +installed, searching all of them might take some time!) + +You can invoke the apropos command from inside Info; see +@ref{Searching Commands}. + +@item --debug=@var{number} +@itemx -x @var{number} +@cindex @code{--debug} (@code{-x}) command line option +@cindex debugging +Print additional debugging information. The argument specifies the +verbosity level, so a higher level includes all the information from +lower levels. For all available debugging output, use +@option{-x@tie{}-1}. Info version @value{VERSION} has these levels: + +@table @code +@item 1 +Print information about file handling, such as looking for @file{dir} +files and nodes written with @samp{--output}. + +@item 2 +Print operations relating to @env{INFOPATH}. + +@item 3 +Print information about node searching. +@end table + +Debugging output goes to standard error. + +@item --directory @var{directory-path} +@itemx -d @var{directory-path} +@cindex @code{--directory} (@code{-d}) command line option +@cindex directory path +@cindex @env{INFOPATH} +@anchor{INFOPATH} +Add @var{directory-path} to the list of directory paths searched +when Info needs to find a file. You may issue @code{--directory} +multiple times; once for each directory which contains Info files, +or with a list of such directories separated by a colon (or semicolon +on MS-DOS/MS-Windows). + +Directories specified in the environment variable @env{INFOPATH} are added +to the directories specified with @code{--directory}, if any. The value of +@code{INFOPATH} is a list of directories usually separated by a colon; +on MS-DOS/MS-Windows systems, the semicolon is used. If the value of +@code{INFOPATH} ends with a colon (or semicolon on MS-DOS/MS-Windows), +the initial list of directories is constructed by appending the +build-time default to the value of @code{INFOPATH}. + +If you do not define @code{INFOPATH}, Info uses a default path defined +when Info was built as the initial list of directories. + +Regardless of whether @code{INFOPATH} is defined, the default +documentation directory defined when Info was built is added to the +search path. If you do not want this directory to be included, set +the @code{infopath-no-defaults} variable to @code{On} +(@pxref{infopath-no-defaults}). + +If the list of directories contains the element @code{PATH}, that +element is replaced by a list of directories derived from the value of +the environment variable @code{PATH}. Each path element of the form +@var{dir/base} is replaced by @var{dir}@code{/share/info} or +@var{dir}@code{/info}, provided that directory exists. + +@item --dribble=@var{file} +@cindex @code{--dribble} command line option +@cindex keystrokes, recording +@cindex remembering user keystrokes +Specify a file where all user keystrokes will be recorded. This file +can be used later to replay the same sequence of commands, see the +@samp{--restore} option below. + +@item --file @var{manual} +@itemx -f @var{manual} +@cindex @code{--file} (@code{-f}) command line option +@cindex Info manual, specifying initial +@cindex initial node, specifying +@cindex startup node, specifying +Specify a particular manual to visit without looking its name up in any +@file{dir} files. + +With this option, it starts by trying to visit +@code{(@var{manual})Top}, i.e., the @code{Top} node in (typically) +@file{@var{manual}.info}. As above, it tries various file extensions +to find the file. If no such file (or node) can be found, Info exits +without doing anything. As with the @file{dir} lookup described above, +any extra @var{menu-or-index-item} arguments are used to locate a node +within the loaded file. + +If @var{manual} is an absolute file name, or begins with @file{./} or +@file{../}, or contains an intermediate directory, Info will only look +for the file in the directory specified, and add this directory to +@code{INFOPATH}. (This is the same as what happens when @code{--file} +is not given.) + +@item --help +@itemx -h +@cindex @code{--help} (@code{-h}) command line option +Output a brief description of the available Info command-line options. + +@item --index-search @var{string} +@cindex @code{--index-search} command line option +@cindex index search, selecting from the command line +@cindex online help, using Info as +After processing all command-line arguments, go to the index in the +selected Info file and search for index entries which match +@var{string}. If such an entry is found, the Info session begins with +displaying the node pointed to by the first matching index entry; +press @kbd{,} to step through the rest of the matching entries. If no +such entry exists, print @samp{no entries found} and exit with nonzero +status. This can be used from another program as a way to provide +online help, or as a quick way of starting to read an Info file at a +certain node when you don't know the exact name of that node. + +When used with the @option{--all} option, @command{info} +displays a menu of matching index entries (just as the +@code{virtual-index} command does; see @ref{Index Commands}). + +This command can also be invoked from inside Info; @pxref{Searching +Commands}. + +@item --init-file @var{INIT-FILE} +@anchor{--init-file} +@cindex @code{--init-file} command line option +Read key bindings and variable settings from @var{INIT-FILE} instead +of the @file{.infokey} file in your home directory. @xref{Custom Key +Bindings}. + +@item --node @var{nodename} +@itemx -n @var{nodename} +@cindex @code{--node} (@code{-n}) command line option +@cindex node, selecting from the command line +Specify a particular node to visit in the initial file that Info +loads. You may specify @code{--node} multiple times: for an interactive +Info, each @var{nodename} is visited in its own window; for a +non-interactive Info (such as when @code{--output} is given) each +@var{nodename} is processed sequentially. + +You can specify both the file and node to the @code{--node} option +using the usual Info syntax, but don't forget to escape the open and +close parentheses and whitespace from the shell; for example:@* +@t{info --node "(emacs)Buffers"} + +@item --output @var{file} +@itemx -o @var{file} +@cindex @code{--output} (@code{-o}) command line option +@cindex file, outputting to +@cindex outputting to a file +Direct output to @var{file}. Each node that Info visits will be +output to @var{file} instead of interactively viewed. A value of +@code{-} for @var{file} means standard output. + +@item --no-raw-escapes +@itemx --raw-escapes, -R +@anchor {--raw-escapes} +@cindex @code{--raw-escapes} (@code{-R}) command line option +@cindex colors in documents +@cindex ANSI escape sequences in documents +By default, Info passes SGR terminal control sequences (also known as +ANSI escape sequences) found in documents directly through to the +terminal. If you use the @code{--no-raw-escapes} options, these +sequences are displayed as other control characters are; for example, an +@kbd{ESC} byte is displayed as @samp{^[}. The @code{--raw-escapes} and +@code{-R} options do not do anything, but are included for completeness. + +@cindex man pages, bold and underline +@vindex GROFF_SGR +Some versions of Groff (@pxref{Top,,,groff,Groff}) produce man pages +with ANSI escape sequences for bold, italics, and underlined +characters, and for colorized text. If your @command{man} command +uses a version of Groff that does this (original GNU Groff does), and +your terminal supports these sequences, Info will display any bold or +underlined text in man pages. Some distributions have modified Groff +to require setting the @code{GROFF_SGR} environment variable to get +these sequences. @xref{Invoking grotty,,, groff, Groff}. + +@item --restore=@var{dribble-file} +@cindex @code{--restore} command line option +@cindex replaying recorded keystrokes +Read keystrokes from @var{dribble-file}, presumably recorded during +previous Info session (see the description of the @samp{--dribble} +option above). When the keystrokes in the files are all read, Info +reverts its input to the usual interactive operation. + +@item --show-malformed-multibytes +@itemx --no-show-malformed-multibytes +@cindex @code{--show-malformed-multibytes} command line option +@cindex malformed multibyte sequences, showing +Show malformed multibyte sequences in the output. By default, such +sequences are dropped. + +@anchor{--show-options} +@item --show-options +@itemx --usage +@itemx -O +@cindex @code{--show-options} (@code{--usage}, @code{-O}) command line option +@cindex command-line options, how to find +@cindex invocation description, how to find +Tell Info to look for the node that describes how to invoke the +program and its command-line options, and begin the session by +displaying that node. It is provided to make it easier to find the +most important usage information in a manual without navigating +through menu hierarchies. The effect is similar to the @code{M-x +goto-invocation} command (@pxref{goto-invocation}) from inside Info. + +@item --speech-friendly +@itemx -b +@cindex @code{--speech-friendly} (@code{-b}) command line option +@cindex speech synthesizers +On MS-DOS/MS-Windows only, this option causes Info to use standard +file I/O functions for screen writes. (By default, Info uses direct +writes to the video memory on these systems, for faster operation and +colored display support.) This allows the speech synthesizers used by +blind persons to catch the output and convert it to audible speech. + +@item --strict-node-location +@cindex @code{--strict-node-location} command line option +This option causes Info not to search ``nearby'' to locate nodes, and +instead strictly use the information provided in the Info file. The +practical use for this option is for debugging programs that write +Info files, to check that they are outputting the correct locations. +Due to bugs and malfeasances in the various Info writing programs over +the years and versions, it is not advisable to ever use this option +when just trying to read documentation. + +@item --subnodes +@cindex @code{--subnodes}, command line option +This option only has meaning when given in conjunction with +@code{--output}. It means to recursively output the nodes appearing in +the menus of each node being output. Menu items which resolve to +external Info files are not output, and neither are menu items which are +members of an index. Each node is only output once. + +@anchor{variable-assignment} +@item -v @var{name}=@var{value} +@itemx --variable=@var{name}=@var{value} +@cindex @code{--variable} (@code{-v}) command line option +@cindex variable assignment +Set the @command{info} variable @var{name} to @var{value}. +@xref{Variables}. + +@item --version +@cindex @code{--version} command line option +@cindex version information +Prints the version information of Info and exits. + +@anchor{--vi-keys} +@item --vi-keys +@cindex @code{--vi-keys} command line option +@cindex vi-like key bindings +@cindex Less-like key bindings +This option binds functions to keys differently, to emulate the key +bindings of @code{vi} and Less. The bindings activated by this option +are documented in @ref{@t{infokey} format}. (@xref{Custom Key Bindings} +for a more general way of altering GNU Info's key bindings.) + +@item --where +@itemx --location +@itemx -w +@cindex @code{--where} (@code{--location}, @code{-w}) command line option +@cindex Info manual location +@cindex Where is an Info manual? +Show the filename that would be read and exit, instead of actually +reading it and starting Info. +@end table + +Finally, Info defines many default key bindings and variables. +@xref{Custom Key Bindings} for information on how to customize these +settings. + +@c FIXME: the feature with lowercasing the file name isn't documented + + +@node Cursor Commands +@chapter Moving the Cursor +@cindex cursor, moving +@cindex moving the cursor + +GNU Info has several commands which allow you to move the cursor about +the screen. +The notation used in this manual to describe keystrokes +is the same as the notation used within the Emacs manual +(@pxref{User Input,,, emacs, The GNU Emacs Manual}). +@kbd{C-@var{x}} means press the @kbd{CTRL} key and the +key @var{x}. @kbd{M-@var{x}} means press the @kbd{META} key and +the key @var{x}. On many terminals the @kbd{META} key is known as +the @kbd{ALT} key. @kbd{SPC} is the space bar. The other keys are +usually called by the names printed on them. + +The following table lists the basic cursor movement commands in Info. +Each entry consists of the key sequence you should type to execute the +cursor movement, the @code{M-x} command name (displayed +in parentheses), and a short description of what the command +does.@footnote{@code{M-x} is also a command; +it invokes @code{execute-extended-command}, letting you run a command +by name. @xref{M-x, , Executing an extended command, emacs, The GNU +Emacs Manual}, for more detailed information.} +All of the cursor motion commands can take a @dfn{numeric} argument +(see @ref{Miscellaneous Commands, @code{universal-argument}} to find +out how to supply them). With a numeric argument, the motion commands +are simply executed that many times; for example, a numeric argument +of 4 given to @code{next-line} causes the cursor to move down 4 lines. +With a negative numeric argument, the motion is reversed; an argument +of @minus{}4 given to the @code{next-line} command would cause the +cursor to move @emph{up} 4 lines. + +@table @asis +@item @kbd{C-n} (@code{next-line}) +@itemx @key{DOWN} (an arrow key) +@kindex C-n +@kindex DOWN (an arrow key) +@findex next-line +Move the cursor down to the next line. + +@item @kbd{C-p} (@code{prev-line}) +@itemx @key{UP} (an arrow key) +@kindex C-p +@kindex UP (an arrow key) +@findex prev-line +Move the cursor up to the previous line. + +@item @kbd{C-a} (@code{beginning-of-line}) +@itemx @key{Home} (on DOS/Windows only) +@kindex C-a, in Info windows +@kindex Home +@findex beginning-of-line +Move the cursor to the start of the current line. + +@item @kbd{C-e} (@code{end-of-line}) +@itemx @key{End} (on DOS/Windows only) +@kindex C-e, in Info windows +@kindex End +@findex end-of-line +Move the cursor to the end of the current line. + +@item @kbd{C-f} (@code{forward-char}) +@itemx @key{RIGHT} (an arrow key) +@kindex C-f, in Info windows +@kindex RIGHT (an arrow key) +@findex forward-char +Move the cursor forward a character. + +@item @kbd{C-b} (@code{backward-char}) +@itemx @key{LEFT} (an arrow key) +@kindex C-b, in Info windows +@kindex LEFT (an arrow key) +@findex backward-char +Move the cursor backward a character. + +@item @kbd{M-f} (@code{forward-word}) +@itemx @kbd{C-@key{RIGHT}} (on DOS/Windows only) +@kindex M-f, in Info windows +@kindex C-RIGHT +@findex forward-word +Move the cursor forward a word. + +@item @kbd{M-b} (@code{backward-word}) +@itemx @kbd{C-@key{LEFT}} (on DOS/Windows only) +@kindex M-b, in Info windows +@kindex C-LEFT +@findex backward-word +Move the cursor backward a word. + +@item @kbd{M-<} (@code{beginning-of-node}) +@itemx @kbd{C-@key{Home}} (on DOS/Windows only) +@itemx @kbd{b} +@kindex b, in Info windows +@kindex M-< +@kindex C-Home +@findex beginning-of-node +Move the cursor to the start of the current node. + +@item @kbd{M->} (@code{end-of-node}) +@itemx @kbd{C-@key{End}} (on DOS/Windows only) +@itemx @kbd{e} +@kindex M-> +@kindex e, in Info windows +@kindex C-End +@findex end-of-node +Move the cursor to the end of the current node. + +@item @kbd{M-r} (@code{move-to-window-line}) +@kindex M-r +@findex move-to-window-line +Move the cursor to a specific line of the window. Without a numeric +argument, @code{M-r} moves the cursor to the start of the line in the +center of the window. With a numeric argument of @var{n}, @code{M-r} +moves the cursor to the start of the @var{n}th line in the window. +@end table + + +@node Scrolling Commands +@chapter Moving Text Within a Window +@cindex scrolling + +Sometimes you are looking at a screenful of text, and only part of the +current paragraph you are reading is visible on the screen. The +commands detailed in this section are used to shift which part of the +current node is visible on the screen. + +@table @asis +@item @key{SPC} (@code{scroll-forward}) +@kindex SPC, in Info windows +@itemx @key{NEXT} +@kindex NEXT +@findex scroll-forward +Shift the text in this window up. That is, show more of the node which +is currently below the bottom of the window. With a numeric argument, +show that many more lines at the bottom of the window; a numeric +argument of 4 would shift all of the text in the window up 4 lines +(discarding the top 4 lines), and show you four new lines at the bottom +of the window. Without a numeric argument, @key{SPC} takes the bottom +two lines of the window and places them at the top of the window, +redisplaying almost a completely new screenful of lines. If you are at +the end of a node, @key{SPC} takes you to the ``next'' node, so that you can +read an entire manual from start to finish by repeating @key{SPC}. + +@kindex PageDown +The @key{NEXT} key is known as the @key{PageDown} key on some +keyboards. + +@item @kbd{C-v} (@code{scroll-forward-page-only}) +@kindex C-v +@findex scroll-forward-page-only +Shift the text in this window up. This is identical to the @key{SPC} +operation above, except that it never scrolls beyond the end of the +current node. + +@item @code{M-x scroll-forward-page-only-set-window} +@findex scroll-forward-page-only-set-window +Scroll forward, like with @kbd{C-v}, but if a numeric argument is +specified, it becomes the default scroll size for subsequent +@code{scroll-forward} and @code{scroll-backward} commands and their +ilk. + +@item @key{DEL} (@code{scroll-backward}) +@kindex DEL, in Info windows +@item @key{PREVIOUS} +@kindex PREVIOUS +@findex scroll-backward +Shift the text in this window down. The inverse of +@code{scroll-forward}. +If you are at the start of a node, @key{DEL} takes you to the +``previous'' node, so that you can read an entire manual from finish to +start by repeating @key{DEL}. The default scroll size can be changed by +invoking the (@code{scroll-backward-page-only-set-window}) command with +a numeric argument. + +@kindex BS (backspace) +If your keyboard lacks the @key{DEL} key, look for a key called +@key{BS}, or @samp{Backspace}, sometimes designated with an arrow which +points to the left, which should perform the same function. + +@kindex PageUp +The @key{PREVIOUS} key is the @key{PageUp} key on many keyboards. Emacs +refers to it by the name @key{PRIOR}. + +@item @kbd{M-v} (@code{scroll-backward-page-only}) +@kindex M-v +@findex scroll-backward-page-only +Shift the text in this window down. The inverse of +@code{scroll-forward-page-only}. Does not scroll beyond the start of +the current node. The default scroll size can be changed by invoking +the @code{scroll-backward-page-only-set-window} command with a numeric +argument. + +@item @code{M-x scroll-backward-page-only-set-window} +@findex scroll-backward-page-only-set-window +Scroll backward, like with @kbd{M-v}, but if a numeric argument is +specified, it becomes the default scroll size for subsequent +@code{scroll-forward} and @code{scroll-backward} commands. + +@item @code{M-x down-line} +@findex down-line +Scroll forward by one line. With a numeric argument, scroll forward +that many lines. + +@item @code{M-x up-line} +@findex up-line +Scroll backward one line. With a numeric argument, scroll backward that +many lines. + +@item @code{M-x scroll-half-screen-down} +@findex scroll-half-screen-down +Scroll forward by half of the screen size. With a numeric argument, +scroll that many lines. If an argument is specified, it becomes the new +default number of lines to scroll for subsequent +@code{scroll-half-screen-down} and @code{scroll-half-screen-up} commands. + +@item @code{M-x scroll-half-screen-up} +@findex scroll-half-screen-up +Scroll back by half of the screen size. With a numeric argument, +scroll that many lines. If an argument is specified, it becomes the new +default number of lines to scroll for subsequent +@code{scroll-half-screen-down} and @code{scroll-half-screen-up} +commands. +@end table + +@cindex scrolling through node structure +The @code{scroll-forward} and @code{scroll-backward} commands can also +move forward and backward through the node structure of the file. If +you press @key{SPC} while viewing the end of a node, or @key{DEL} while +viewing the beginning of a node, what happens is controlled by the +variable @code{scroll-behavior} (@pxref{scroll-behavior}). + +The @code{scroll-forward-page-only} and @code{scroll-backward-page-only} +commands never scroll beyond the current node. + +@table @asis +@item @kbd{C-l} (@code{redraw-display}) +@kindex C-l +@findex redraw-display +Redraw the display from scratch, or shift the line containing the cursor +to a specified location. With no numeric argument, @samp{C-l} clears +the screen, and then redraws its entire contents. Given a numeric +argument of @var{n}, the line containing the cursor is shifted so that +it is on the @var{n}th line of the window. + +@item @kbd{C-x @kbd{w}} (@code{toggle-wrap}) +@kindex C-w +@findex toggle-wrap +Toggles the state of line wrapping in the current window. Normally, +lines which are longer than the screen width @dfn{wrap}, i.e., they are +continued on the next line. Lines which wrap have a @samp{\} appearing +in the rightmost column of the screen. You can cause such lines to be +terminated at the rightmost column by changing the state of line +wrapping in the window with @code{C-x w}. When a line which needs more +space than one screen width to display is displayed, a @samp{$} appears +in the rightmost column of the screen, and the remainder of the line is +invisible. When long lines are truncated, the mode line displays the +@samp{$} character near its left edge. +@end table + + +@node Node Commands +@chapter Selecting a Node +@cindex nodes, selection of + +This section details the numerous Info commands which select a new node +to view in the current window. + +The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and +@samp{l}. + +When you are viewing a node, the top line of the node contains some Info +@dfn{pointers} which describe where the next, previous, and up nodes +are. Info uses this line to move about the node structure of the file +when you use the following commands: + +@table @asis +@item @kbd{n} (@code{next-node}) +@itemx @kbd{C-@key{NEXT}} (on DOS/Windows only) +@kindex n +@kindex C-NEXT +@findex next-node +Select the `Next' node. + +@kindex C-PgDn +The @key{NEXT} key is known as the @key{PgDn} key on some +keyboards. + +@item @kbd{p} (@code{prev-node}) +@itemx @kbd{C-@key{PREVIOUS}} (on DOS/Windows only) +@kindex p +@kindex C-PREVIOUS +@findex prev-node +Select the `Prev' node. + +@kindex C-PgUp +The @key{PREVIOUS} key is known as the @key{PgUp} key on some +keyboards. + +@item @kbd{u} (@code{up-node}) +@itemx @kbd{C-@key{UP}} (an arrow key on DOS/Windows only) +@kindex u +@kindex C-UP +@findex up-node +Select the `Up' node. +@end table + +You can easily select a node that you have already viewed in this window +by using the @samp{l} command---this name stands for ``last'', and +actually moves backwards through the history of visited nodes for this +window. This is handy when you followed a reference to another node, +possibly to read about a related issue, and would like then to resume +reading at the same place where you started the excursion. + +Each node where you press @samp{l} is discarded from the history. Thus, +by the time you get to the first node you visited in a window, the +entire history of that window is discarded. + +@table @asis +@item @kbd{l} (@code{history-node}) +@itemx @kbd{C-@key{CENTER}} (on DOS/Windows only) +@kindex l +@kindex C-CENTER +@findex history-node +Pop the most recently selected node in this window from the node +history. +@end table + +Two additional commands make it easy to select the most commonly +selected nodes; they are @samp{t} and @samp{d}. + +@table @asis +@item @kbd{t} (@code{top-node}) +@kindex t +@findex top-node +Select the node @samp{Top} in the current Info file. + +@item @kbd{d} (@code{dir-node}) +@kindex d +@findex dir-node +Select the directory node (i.e., the node @samp{(dir)}). +@end table + +Here are some other commands which immediately result in the selection +of a different node in the current window: + +@table @asis +@item @kbd{<} (@code{first-node}) +@kindex < +@findex first-node +Selects the first node which appears in this file. This node is most +often @samp{Top}, but it does not have to be. With a numeric argument +@var{N}, select the @var{N}th node (the first node is node 1). An +argument of zero is the same as the argument of 1. + +@item @kbd{>} (@code{last-node}) +@kindex > +@findex last-node +Select the last node which appears in this file. With a numeric argument +@var{N}, select the @var{N}th node (the first node is node 1). An +argument of zero is the same as no argument, i.e., it selects the last +node. + +@item @kbd{]} (@code{global-next-node}) +@kindex ] +@findex global-next-node +Move forward through the node structure. If the node that you are +currently viewing has a menu, select the first menu item. Otherwise, +if this node has a @samp{Next} pointer, follow it. If there is no menu +and no @samp{Next} pointer, then follow @samp{Up} pointers until there +is a @samp{Next} pointer, and then follow it. + +@item @kbd{[} (@code{global-prev-node}) +@kindex [ +@findex global-prev-node +Move backward through the node structure. If the node that you are +currently viewing has a @samp{Prev} pointer, that node is selected. +Otherwise, if the node has an @samp{Up} pointer, that node is selected, +and if it has a menu, the last item in the menu is selected. +@end table + +You can get the same behavior as @code{global-next-node} and +@code{global-prev-node} while simply scrolling through the file with +@key{SPC} and @key{DEL} (@pxref{scroll-behavior}). + +@table @asis +@anchor{goto-node} +@item @kbd{g} (@code{goto-node}) +@kindex g +@findex goto-node +Read the name of a node and select it. If the desired node resides in +some other file, you must type the node as it appears in that Info file, +and include the name of the other file. For example, + +@example +@code{g(emacs)Buffers} +@end example + +@noindent +finds the node @samp{Buffers} in the Info file @file{emacs}. + +While reading the node name, completion (@pxref{The Echo Area, +completion}) is only done for the nodes which reside in one of the Info +files that were loaded in the current Info session. + +@anchor{goto-invocation} +@item @kbd{O} (@code{goto-invocation}) +@kindex O +@findex goto-invocation +@cindex finding the Invocation node +Read the name of a program and look for a node in the current Info file +which describes the invocation and the command-line options for that +program. The default program name is derived from the name of the +current Info file. This command does the same as the +@samp{--show-options} command-line option (@pxref{--show-options}), but +it also allows to specify the program name; this is important for those +manuals which describe several programs. + +If you need to find the Invocation node of a program that is documented +in another Info file, you need to visit that file before invoking +@samp{O}. For example, if you are reading the Emacs manual and want to +see the command-line options of the @code{makeinfo} program, type @kbd{g +(texinfo) @key{RET}} and then @kbd{I makeinfo @key{RET}}. If you don't +know what Info file documents the command, or if invoking @samp{O} +doesn't display the right node, go to the @samp{(dir)} node (using the +@samp{d} command) and invoke @samp{O} from there. + +@item @kbd{G} (@code{menu-sequence}) +@kindex G +@findex menu-sequence +@cindex menu, following, from inside Info +Read a sequence of menu entries and follow it. Info prompts for a +sequence of menu items separated by commas. (Since commas are not +allowed in a node name, they are a natural choice for a delimiter in a +list of menu items.) Info then looks up the first item in the menu of +the node @samp{(dir)} (if the @samp{(dir)} node cannot be found, Info +uses @samp{Top}). If such an entry is found, Info goes to the node it +points to and looks up the second item in the menu of that node, etc. +In other words, you can specify a complete path which descends through +the menu hierarchy of a particular Info file starting at the +@samp{(dir)} node. This has the same effect as if you typed the menu +item sequence on Info's command line, see @ref{command-line menu items,, +Info command-line arguments processing}. For example, + +@example + @kbd{G Texinfo,Overview,Reporting Bugs @key{RET}} +@end example + +@noindent +displays the node @samp{Reporting Bugs} in the Texinfo manual. (You +don't actually need to type the menu items in their full length, or in +their exact letter-case. However, if you do type the menu items +exactly, Info will find it faster.) + +If any of the menu items you type are not found, Info stops at the last +entry it did find and reports an error. + +@item @kbd{C-x C-f} (@code{view-file}) +@kindex C-x C-f +@findex view-file +Read the name of a file and selects the entire file. The command +@example +@code{C-x C-f @var{filename}} +@end example +is equivalent to typing +@example +@code{g(@var{filename})*} +@end example + +@item @kbd{C-x C-b} (@code{list-visited-nodes}) +@kindex C-x C-b +@findex list-visited-nodes +Make a window containing a menu of all of the currently visited nodes. +This window becomes the selected window, and you may use the standard +Info commands within it. + +@item @kbd{C-x @kbd{b}} (@code{select-visited-node}) +@kindex C-x b +@findex select-visited-node +Select a node which has been previously visited in a visible window. +This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is +created. + +@item @code{M-x man} +@findex man +@cindex man pages, displaying +Read the name of a man page to load and display. This uses the @command{man} +command on your system to retrieve the contents of the requested man page. +See also @pxref{--raw-escapes}. + +@end table + + +@node Searching Commands +@chapter Searching an Info File +@cindex searching + +GNU Info allows you to search for a sequence of characters throughout an +entire Info file. Here are the commands to do this: + +@table @asis +@item @kbd{s} (@code{search}) +@itemx @kbd{/} +@kindex s +@kindex / +@findex search +@cindex regular expression search +Read a string in the echo area and search for it, either as a regular +expression (by default) or a literal string. If the string includes +upper-case characters, the Info file is searched case-sensitively; +otherwise Info ignores the letter case. With a numeric argument of +@var{N}, search for @var{N}th occurrence of the string. Negative +arguments search backwards. + +@item @kbd{?} (@code{search-backward}) +@kindex ? +@findex search-backward +Read a string in the echo area and search backward through the Info file +for that string. If the string includes upper-case characters, the Info +file is searched case-sensitively; otherwise Info ignores the letter +case. With a numeric argument of @var{N}, search for @var{N}th +occurrence of the string. Negative arguments search forward. + +@anchor{repeated-search} +@item @kbd{C-x @kbd{n}} (@code{search-next}) +@itemx @kbd{@}} +@kindex C-x n +@kindex @} +@findex search-next +@cindex repeated search +Search forwards for the string used for the last search command. +Case sensitivity and use of regular expressions are kept the same. With +a numeric argument of @var{n}, search for @var{n}th next occurrence. + +By default, the search starts at the position immediately following +the cursor. However, if the variable @code{search-skip-screen} +(@pxref{Variables,, @code{search-skip-screen}}) is set, it starts at +the beginning of the next page, thereby skipping all visibly displayed +lines. + +@item @kbd{C-x @kbd{N}} (@code{search-previous}) +@itemx @kbd{@{} +@kindex C-x N +@kindex @{ +@findex search-previous +Just like @code{search-next}, but in reverse. You can use +@code{search-next} and @code{search-previous} together to move forward +and backward through matches. @code{search-previous} usually goes to +the place in the file that was displayed before an immediately preceding +@code{search-next}, and vice versa.@footnote{This sometimes doesn't +happen when @code{search-skip-screen} is @code{On}, and the search goes +across nodes.} + + +@item @kbd{R} (@code{toggle-regexp}) +@kindex R +@findex toggle-regexp +Toggle between using regular expressions and literal strings for +searching. Info uses so-called `extended' regular expression syntax +(@pxref{Regular Expressions,,, grep, GNU Grep}). + +@item @kbd{S} (@code{search-case-sensitively}) +@kindex S +@findex search-case-sensitively +@cindex search, case-sensitive +@cindex case-sensitive search +Read a string in the echo area and search for it case-sensitively, even +if the string includes only lower-case letters. With a numeric argument +of @var{N}, search for @var{N}th occurrence of the string. Negative +arguments search backwards. + +@item @kbd{C-s} (@code{isearch-forward}) +@kindex C-s +@findex isearch-forward +@cindex incremental search +Interactively search forward through the Info file for a string as you +type it. If the string includes upper-case characters, the search is +case-sensitive; otherwise Info ignores the letter case. + +@item @kbd{C-r} (@code{isearch-backward}) +@kindex C-r +@findex isearch-backward +Interactively search backward through the Info file for a string as +you type it. If the string includes upper-case characters, the search +is case-sensitive; otherwise Info ignores the letter case. + +@item @kbd{M-/} (@code{tree-search}) +@findex tree-search +Recursively search this node and any subnodes listed in menus for a +string. + +@item @kbd{M-@}} (@code{tree-search-next}) +@itemx @kbd{M-@{} (@code{tree-search-previous}) +@findex tree-search-next +@findex tree-search-previous +Go forwards and backwards through the matches for an active tree search. +@end table + +The most basic searching command is @samp{s} or @samp{/} +(@code{search}). The @samp{s} command prompts you for a string in the +echo area, and then searches the remainder of the Info file for an +occurrence of that string. If the string is found, the node containing +it is selected, and the cursor is left positioned at the start of the +found string. Subsequent @samp{s} commands show you the default search +string; pressing @key{RET} instead of typing a new string will use the +default search string. + +@dfn{Incremental searching} is similar to basic searching, but the +string is looked up while you are typing it, instead of waiting until +the entire search string has been specified. + +The tree search can be used from the @code{dir} node to search through +all Info files installed on the system. It can also be used to search +through a particular chapter of a manual when you are not interested in +matches in other chapters. + +@vindex highlight-searches +@findex clear-search +If the @code{highlight-searches} variable is set, matches from search +commands will be highlighted. @xref{Variables,, @code{highlight-searches}}. +Use the @kbd{M-x clear-search} command to clear any search highlights. + +@cindex search, and case-sensitivity +@cindex case-sensitivity, and search +Both incremental and non-incremental search by default ignore the case +of letters when comparing the Info file text with the search string. +However, an uppercase letter in the search string makes the search +case-sensitive. You can force a case-sensitive non-incremental search, +even for a string that includes only lower-case letters, by using the +@samp{S} command (@code{search-case-sensitively}). The @samp{n} and +@samp{N} commands operate case-sensitively if the last search command +was @samp{S}. + +Normally, the search pattern should not be shorter than some +predefined limit. By default, this limit is set to 1 character. +@xref{min-search-length} for more information on this. + + +@node Index Commands +@chapter Index Commands +@cindex index +@cindex indices +@cindex indexes + +GNU Info has commands to search through the indices of an Info file, +which helps you find areas within an Info file which discuss a +particular topic. + +@table @asis +@item @kbd{i} (@code{index-search}) +@kindex i +@findex index-search +@cindex index, searching +@cindex searching, in the indices +Look up a string in the indices for this Info file, and select a node +to which the found index entry points. + +@item @kbd{I} (@code{virtual-index}) +@kindex I +@findex virtual-index +@cindex index, virtual +Look up a string in the indices for this Info file, and show all the +matches in a new virtual node, synthesized on the fly. + +@item @kbd{,} (@code{next-index-match}) +@kindex , +@findex next-index-match +Move to the node containing the next matching index item from the last +@samp{i} command. + +@item @kbd{M-x index-apropos} +@findex index-apropos +Grovel the indices of all the known Info files on your system for a +string, and build a menu of the possible matches. +@end table + +The most efficient means of finding something quickly in a manual is +the @samp{i} command (@code{index-search}). This command prompts for +a string, and then looks for that string in all the indices of the +current Info manual. If it finds a matching index entry, it displays +the node to which that entry refers and prints the full text of the +entry in the echo area. You can press @samp{,} +(@code{next-index-match}) to find more matches. A good Info manual +has all of its important concepts indexed, so the @samp{i} command +lets you use a manual as a reference. + +If you don't know what manual documents something, try the @kbd{M-x +index-apropos} command. It prompts for a string and then looks up +that string in all the indices of all the Info documents installed on +your system. It can also be invoked from the command line; see +@ref{--apropos}. + + +@node Xref Commands +@chapter Selecting Cross-references + +We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up} +pointers which appear at the top of a node. In addition to these +pointers, a node may contain other pointers which refer you to a +different node, perhaps in another Info file. Such pointers are called +@dfn{cross-references}, or @dfn{xrefs} for short. + +@menu +* Parts of an Xref:: What a cross-reference is made of. +* Selecting Xrefs:: Commands for selecting menu or note items. +@end menu + +@node Parts of an Xref +@section Parts of an Xref + +Cross-references have two major parts: the first part is called the +@dfn{label}; it is the name that you can use to refer to the cross +reference, and the second is the @dfn{target}; it is the full name of +the node that the cross-reference points to. + +The target is separated from the label by a colon @samp{:}; first the +label appears, and then the target. For example, in the sample menu +cross-reference below, the single colon separates the label from the +target. + +@example +* Foo Label: Foo Target. More information about Foo. +@end example + +Note the @samp{.} which ends the name of the target. The @samp{.} is +not part of the target; it serves only to let Info know where the target +name ends. + +A shorthand way of specifying references allows two adjacent colons to +stand for a target name which is the same as the label name: + +@example +* Foo Commands:: Commands pertaining to Foo. +@end example + +In the above example, the name of the target is the same as the name of +the label, in this case @code{Foo Commands}. + +You will normally see two types of cross-reference while viewing nodes: +@dfn{menu} references, and @dfn{note} references. Menu references +appear within a node's menu; they begin with a @samp{*} at the beginning +of a line, and continue with a label, a target, and a comment which +describes what the contents of the node pointed to contains. + +Note references appear within the body of the node text; they begin with +@code{*Note}, and continue with a label and a target. + +Like @samp{Next}, @samp{Prev}, and @samp{Up} pointers, cross-references +can point to any valid node. They are used to refer you to a place +where more detailed information can be found on a particular subject. +Here is a cross-reference which points to a node within the Texinfo +documentation: @xref{xref, , Writing an Xref, texinfo, the Texinfo +Manual}, for more information on creating your own texinfo cross +references. + +@node Selecting Xrefs +@section Selecting Xrefs + +The following table lists the Info commands which operate on menu items. + +@table @asis +@item @kbd{1} (@code{menu-digit}) +@itemx @kbd{2} @dots{} @kbd{9} +@itemx @kbd{M-1}, vi-like operation +@itemx @kbd{M-2} @dots{} @kbd{M-9}, vi-like operation +@cindex 1 @dots{} 9, in Info windows +@cindex M-1 @dots{} M-9, vi-like operation +@kindex 1 @dots{} 9, in Info windows +@kindex M-1 @dots{} M-9, vi-like operation +@findex menu-digit +Within an Info window, pressing a single digit, (such as @samp{1}), +selects that menu item, and places its node in the current window. +For convenience, there is one exception; pressing @samp{0} selects the +@emph{last} item in the node's menu. When @samp{--vi-keys} is in +effect, digits set the numeric argument, so these commands are remapped +to their @samp{M-} varieties. For example, to select the last menu +item, press @kbd{M-0}. + +@item @kbd{0} (@code{last-menu-item}) +@itemx @kbd{M-0}, vi-like operation +@kindex 0, in Info windows +@kindex M-0, vi-like operation +@findex last-menu-item +Select the last item in the current node's menu. + +@item @kbd{m} (@code{menu-item}) +@kindex m +@findex menu-item +Reads the name of a menu item in the echo area and selects its node. +Completion is available while reading the menu label. @xref{The Echo +Area, completion}. + +@item @kbd{M-x find-menu} +@findex find-menu +Move the cursor to the start of this node's menu. +@end table + +This table lists the Info commands which operate on cross-references. + +@table @asis +@item @kbd{f} (@code{xref-item}) +@itemx @kbd{r} +@kindex f +@kindex r +@findex xref-item +Reads the name of a note cross-reference in the echo area and selects +its node. Completion is available while reading the cross-reference +label. @xref{The Echo Area, completion}. +@end table + +Finally, the next few commands operate on menu or note references alike: + +@table @asis +@item @key{TAB} (@code{move-to-next-xref}) +@kindex TAB, in Info windows +@findex move-to-next-xref +Move the cursor to the start of the next nearest menu item or note +reference in this node. You can then use @key{RET} +(@code{select-reference-this-line}) to select the menu or note reference. + +@item @kbd{M-TAB} (@code{move-to-prev-xref}) +@itemx @kbd{BackTab} +@itemx @kbd{Shift-@key{TAB}} (on DOS/Windows only) +@kindex M-TAB, in Info windows +@findex move-to-prev-xref +Move the cursor the start of the nearest previous menu item or note +reference in this node. + +@kindex Shift-TAB, in Info windows +@kindex BackTab, in Info windows +The @kbd{BackTab} key can be produced on some terminals with +@kbd{Shift-@key{TAB}}. + +@item @key{RET} (@code{select-reference-this-line}) +@kindex RET, in Info windows +@findex select-reference-this-line +Select the menu item or note reference appearing on this line. +@end table + + +@node Window Commands +@chapter Manipulating Multiple Windows +@cindex windows, manipulating + +A @dfn{window} is a place to show the text of a node. Windows have a +view area where the text of the node is displayed, and an associated +@dfn{mode line}, which briefly describes the node being viewed. + +GNU Info supports multiple windows appearing in a single screen; each +window is separated from the next by its mode line. At any time, there +is only one @dfn{active} window, that is, the window in which the cursor +appears. There are commands available for creating windows, changing +the size of windows, selecting which window is active, and for deleting +windows. + +@menu +* The Mode Line:: What appears in the mode line? +* Basic Windows:: Manipulating windows in Info. +* The Echo Area:: Used for displaying errors and reading input. +@end menu + +@node The Mode Line +@section The Mode Line + +A @dfn{mode line} is a line of inverse video which appears at the bottom +of an Info window. It describes the contents of the window just above +it; this information includes the name of the file and node appearing in +that window, the number of screen lines it takes to display the node, +and the percentage of text that is above the top of the window. + +Here is a sample mode line for a window containing a file +named @file{dir}, showing the node @samp{Top}. + +@example +@group +-----Info: (dir)Top, 40 lines --Top------------------------------------- + ^^ ^ ^^^ ^^ + (file)Node #lines where +@end group +@end example + +Truncation of long lines (as opposed to wrapping them to the next +display line, @pxref{Scrolling Commands, toggle-wrap}) is indicated by a +@samp{$} at the left edge of the mode line: + +@example +--$--Info: (texinfo)Top, 480 lines --Top-------------------------------- +@end example + +When Info makes a node internally, such that there is no corresponding +info file on disk, the name of the node is surrounded by asterisks +(@samp{*}). The name itself tells you what the contents of the window +are; the sample mode line below shows an internally constructed node +showing possible completions: + +@example +-----Info: *Completions*, 7 lines --All--------------------------------- +@end example + +@node Basic Windows +@section Window Commands + +It can be convenient to view more than one node at a time. To allow +this, Info can display more than one @dfn{window}. Each window has its +own mode line (@pxref{The Mode Line}) and history of nodes viewed in that +window (@pxref{Node Commands, , @code{history-node}}). + +@table @asis +@item @kbd{C-x @kbd{o}} (@code{next-window}) +@cindex windows, selecting +@kindex C-x o +@findex next-window +Select the next window on the screen. Note that the echo area can only be +selected if it is already in use, and you have left it temporarily. +Normally, @samp{C-x o} simply moves the cursor into the next window on +the screen, or if you are already within the last window, into the first +window on the screen. Given a numeric argument, @samp{C-x o} moves over +that many windows. A negative argument causes @samp{C-x o} to select +the previous window on the screen. + +@item @kbd{M-x prev-window} +@findex prev-window +Select the previous window on the screen. This is identical to +@samp{C-x o} with a negative argument. + +@item @kbd{C-x @kbd{2}} (@code{split-window}) +@cindex windows, creating +@kindex C-x 2 +@findex split-window +Split the current window into two windows, both showing the same node. +Each window is one half the size of the original window, and the +cursor remains in the original window. The variable +@code{automatic-tiling} can cause all of the windows on the screen to +be resized for you automatically (@pxref{Variables,, +@code{automatic-tiling}}). + +@item @kbd{C-x @kbd{0}} (@code{delete-window}) +@cindex windows, deleting +@kindex C-x 0 +@findex delete-window +Delete the current window from the screen. If you have made too many +windows and your screen appears cluttered, this is the way to get rid of +some of them. + +@item @kbd{C-x @kbd{1}} (@code{keep-one-window}) +@kindex C-x 1 +@findex keep-one-window +Delete all of the windows excepting the current one. + +@item @kbd{ESC @kbd{C-v}} (@code{scroll-other-window}) +@kindex ESC C-v, in Info windows +@findex scroll-other-window +Scroll the other window, in the same fashion that @samp{C-v} might +scroll the current window. Given a negative argument, scroll the +``other'' window backward. + +@item @kbd{C-x @kbd{^}} (@code{grow-window}) +@kindex C-x ^ +@findex grow-window +Grow (or shrink) the current window. Given a numeric argument, grow +the current window that many lines; with a negative numeric argument, +shrink the window instead. + +@item @kbd{C-x @kbd{t}} (@code{tile-windows}) +@cindex tiling +@kindex C-x t +@findex tile-windows +Divide the available screen space among all of the visible windows. +Each window is given an equal portion of the screen in which to +display its contents. The variable @code{automatic-tiling} can cause +@code{tile-windows} to be called when a window is created or deleted. +@xref{Variables,, @code{automatic-tiling}}. +@end table + +@node The Echo Area +@section The Echo Area +@cindex echo area + +The @dfn{echo area} is a one line window which appears at the bottom of +the screen. It is used to display informative or error messages, and to +read lines of input from you when that is necessary. Almost all of the +commands available in the echo area are identical to their Emacs +counterparts, so please refer to that documentation for greater depth of +discussion on the concepts of editing a line of text. The following +table briefly lists the commands that are available while input is being +read in the echo area: + +@table @asis +@item @kbd{C-f} (@code{echo-area-forward}) +@itemx @key{RIGHT} (an arrow key) +@kindex C-f, in the echo area +@kindex RIGHT, in the echo area +@findex echo-area-forward +Move forward a character. + +@item @kbd{C-b} (@code{echo-area-backward}) +@itemx @key{LEFT} (an arrow key) +@kindex LEFT, in the echo area +@kindex C-b, in the echo area +@findex echo-area-backward +Move backward a character. + +@item @kbd{C-a} (@code{echo-area-beg-of-line}) +@kindex C-a, in the echo area +@findex echo-area-beg-of-line +Move to the start of the input line. + +@item @kbd{C-e} (@code{echo-area-end-of-line}) +@kindex C-e, in the echo area +@findex echo-area-end-of-line +Move to the end of the input line. + +@item @kbd{M-f} (@code{echo-area-forward-word}) +@itemx @kbd{C-@key{RIGHT}} (DOS/Windows only) +@kindex M-f, in the echo area +@findex echo-area-forward-word +Move forward a word. + +@kindex C-RIGHT, in the echo area +On DOS/Windows, @kbd{C-@key{RIGHT}} moves forward by words. + +@item @kbd{M-b} (@code{echo-area-backward-word}) +@itemx @kbd{C-@key{LEFT}} (DOS/Windows only) +@kindex M-b, in the echo area +@findex echo-area-backward-word +Move backward a word. + +@kindex C-LEFT, in the echo area +On DOS/Windows, @kbd{C-@key{LEFT}} moves backward by words. + +@item @kbd{C-d} (@code{echo-area-delete}) +@kindex C-d, in the echo area +@findex echo-area-delete +Delete the character under the cursor. + +@item @key{DEL} (@code{echo-area-rubout}) +@kindex DEL, in the echo area +@findex echo-area-rubout +Delete the character behind the cursor. + +On some keyboards, this key is designated @key{BS}, for +@samp{Backspace}. Those keyboards will usually bind @key{DEL} in the +echo area to @code{echo-area-delete}. + +@item @kbd{C-g} (@code{echo-area-abort}) +@kindex C-g, in the echo area +@findex echo-area-abort +Cancel or quit the current operation. If completion is being read, this +command discards the text of the input line which does not match any +completion. If the input line is empty, it aborts the calling function. + +@item @key{RET} (@code{echo-area-newline}) +@kindex RET, in the echo area +@findex echo-area-newline +Accept (or forces completion of) the current input line. + +@item @kbd{C-q} (@code{echo-area-quoted-insert}) +@kindex C-q, in the echo area +@findex echo-area-quoted-insert +Insert the next character verbatim. This is how you can insert control +characters into a search string, for example, or the @samp{?} character +when Info prompts with completion. + +@item @kbd{M-TAB} (@code{echo-area-tab-insert}) +@itemx @kbd{Shift-@key{TAB}} (on DOS/Windows only) +@kindex M-TAB, in the echo area +@kindex Shift-TAB, in the echo area +@findex echo-area-tab-insert +Insert a TAB character. + +@kindex Shift-TAB, in the echo area +@kindex BackTab, in the echo area +On DOS/Windows only, the @kbd{Shift-@key{TAB}} key is an alias for +@kbd{M-@key{TAB}}. This key is sometimes called @samp{BackTab}. + +@item @kbd{C-t} (@code{echo-area-transpose-chars}) +@kindex C-t, in the echo area +@findex echo-area-transpose-chars +Transpose the characters at the cursor. + +@item @var{printing character} +@kindex printing characters, in the echo area +Insert the character. + +@end table + +The next group of commands deal with @dfn{killing}, and @dfn{yanking} +text. (Sometimes these operations are called @dfn{cut} and +@dfn{paste}, respectively.) For an in-depth discussion, see +@ref{Killing, , Killing and Deleting, emacs, the GNU Emacs Manual}. + +@table @asis +@item @kbd{M-d} (@code{echo-area-kill-word}) +@kindex M-d, in the echo area +@findex echo-area-kill-word +Kill the word following the cursor. + +@item @kbd{M-@key{DEL}} (@code{echo-area-backward-kill-word}) +@itemx @kbd{M-@key{BS}} +@kindex M-DEL, in the echo area +@findex echo-area-backward-kill-word +Kill the word preceding the cursor. + +@kindex M-BS, in the echo area +On some keyboards, the @samp{Backspace} key is used instead of +@code{DEL}, so @code{M-@key{Backspace}} has the same effect as +@code{M-@key{DEL}}. + +@item @kbd{C-k} (@code{echo-area-kill-line}) +@kindex C-k, in the echo area +@findex echo-area-kill-line +Kill the text from the cursor to the end of the line. + +@item @kbd{C-x @key{DEL}} (@code{echo-area-backward-kill-line}) +@kindex C-x DEL, in the echo area +@findex echo-area-backward-kill-line +Kill the text from the cursor to the beginning of the line. + +@item @kbd{C-y} (@code{echo-area-yank}) +@kindex C-y, in the echo area +@findex echo-area-yank +Yank back the contents of the last kill. + +@item @kbd{M-y} (@code{echo-area-yank-pop}) +@kindex M-y, in the echo area +@findex echo-area-yank-pop +Yank back a previous kill, removing the last yanked text first. +@end table + +@cindex completion +Sometimes when reading input in the echo area, the command that needed +input will only accept one of a list of several choices. The choices +represent the @dfn{possible completions}, and you must respond with one +of them. Since there are a limited number of responses you can make, +Info allows you to abbreviate what you type, only typing as much of the +response as is necessary to uniquely identify it. In addition, you can +request Info to fill in as much of the response as is possible; this +is called @dfn{completion}. + +The following commands are available when completing in the echo area: + +@table @asis +@item @key{TAB} (@code{echo-area-complete}) +@kindex TAB, in the echo area +@findex echo-area-complete +Insert as much of a completion as is possible. Otherwise, +display a window containing a list of the possible completions of what +you have typed so far. For example, if the available choices are: + +@example +@group +bar +foliate +food +forget +@end group +@end example + +@noindent +and you have typed an @samp{f}, followed by @key{TAB}, this +would result in @samp{fo} appearing in the echo area, since +all of the choices which begin with @samp{f} continue with @samp{o}. + +Now if you type @key{TAB} again, Info will pop +up a window showing a node called @samp{*Completions*} which lists the +possible completions like this: + +@example +@group +3 completions: +foliate food +forget +@end group +@end example + +@noindent +i.e., all of the choices which begin with @samp{fo}. + +Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate} +appearing in the echo area, since that is the only choice which begins +with @samp{fol}. + +@item @key{ESC C-v} (@code{echo-area-scroll-completions-window}) +@kindex ESC C-v, in the echo area +@findex echo-area-scroll-completions-window +Scroll the completions window, if that is visible, or the ``other'' +window if not. +@end table + + +@node Printing Nodes +@chapter Printing Nodes +@cindex printing + +In general, we recommend that you use @TeX{} to format the document and +print sections of it, by running @code{tex} on the Texinfo source file. +However, you may wish to print out the contents of a node as a quick +reference document for later use, or if you don't have @TeX{} installed. +Info provides you with a command for doing this. + +@table @asis +@item @kbd{M-x print-node} +@findex print-node +@cindex @env{INFO_PRINT_COMMAND}, environment variable +Pipe the contents of the current node through the command in the +environment variable @env{INFO_PRINT_COMMAND}. If the variable does not +exist, the node is simply piped to @code{lpr} (on DOS/Windows, the +default is to print the node to the local printer device, @file{PRN}). + +@cindex printing nodes to the local printer +@cindex local printer device +The value of @env{INFO_PRINT_COMMAND} may begin with the @samp{>} +character, as in @samp{>/dev/printer}, in which case Info treats the +rest as the name of a file or a device. Instead of piping to a command, +Info opens the file, writes the node contents, and closes the file, +under the assumption that text written to that file will be printed by +the underlying OS. +@end table + + +@node Miscellaneous Commands +@chapter Miscellaneous Commands + +GNU Info contains several commands which self-document GNU Info: + +@table @asis +@item @kbd{M-x describe-command} +@cindex functions, describing +@cindex commands, describing +@findex describe-command +Read the name of an Info command in the echo area and then display a +brief description of what that command does. + +@item @kbd{M-x describe-key} +@cindex keys, describing +@findex describe-key +Read a key sequence in the echo area, and then display the name and +documentation of the Info command that the key sequence invokes. + +@item @kbd{M-x describe-variable} +Read the name of a variable in the echo area and then display a brief +description of what the variable affects. + +@item @kbd{M-x where-is} +@findex where-is +Read the name of an Info command in the echo area, and then display +a key sequence which can be typed in order to invoke that command. + +@item @kbd{H} (@code{get-help-window}) +@itemx @key{F1} (on DOS/Windows only) +@kindex C-h +@kindex ?, in Info windows +@kindex F1 +@findex get-help-window +Create (or Move into) the window displaying @code{*Help*}, and place +a node containing a quick reference card into it. This window displays +the most concise information about GNU Info available. + +@item @kbd{h} (@code{get-info-help-node}) +@kindex h +@findex get-info-help-node +Try hard to visit the node @code{(info)Help}. The Info file +@file{info.texi} distributed with GNU Emacs contains +this node. Of course, the file must first be processed with +@code{makeinfo}, and then placed into the location of your Info directory. + +@item @kbd{=} (@code{display-file-info}) +@cindex current file, information about +@findex display-file-info +@kindex =, in Info windows +Show information about what's currently being viewed in the echo area: +the Info file name, and current line number and percentage within the +current node. + +@item @kbd{M-x info-version} +@findex info-version +Display the name and version of the currently running Info program. + +@end table + +Here are the commands for creating a numeric argument: + +@table @asis +@item @kbd{C-u} (@code{universal-argument}) +@cindex numeric arguments +@kindex C-u +@findex universal-argument +Start (or multiply by 4) the current numeric argument. @samp{C-u} is +a good way to give a small numeric argument to cursor movement or +scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while +@samp{C-u C-u C-n} moves the cursor down 16 lines. @samp{C-u} followed +by digit keys sets the numeric argument to the number thus typed: +@kbd{C-u 1 2 0} sets the argument to 120. + +@item @kbd{M-1} (@code{add-digit-to-numeric-arg}) +@itemx @kbd{1}, vi-like operation +@itemx @kbd{M-2} @dots{} @kbd{M-9} +@itemx @kbd{2} @dots{} @kbd{9}, vi-like operation +@itemx @kbd{M-0} +@itemx @kbd{0}, vi-like operation +@kindex M-0 @dots{} M-9 +@kindex 0 @dots{} 9, vi-like operation +@findex add-digit-to-numeric-arg +Add the digit value of the invoking key to the current numeric +argument. Once Info is reading a numeric argument, you may just type +the digits of the argument, without the Meta prefix. For example, you +might give @samp{C-l} a numeric argument of 32 by typing: + +@example +@kbd{C-u 3 2 C-l} +@end example + +@noindent +or + +@example +@kbd{M-3 2 C-l} +@end example + +@item @kbd{M--} (@code{add-digit-to-numeric-arg}) +@itemx @kbd{-} +@kindex M-- +@kindex - +@cindex negative arguments +@cindex arguments, negative +@cindex numeric arguments, negative +To make a negative argument, type @kbd{-}. Typing @kbd{-} alone makes +a negative argument with a value of @minus{}1. If you continue to +type digit or Meta-digit keys after @kbd{-}, the result is a negative +number produced by those digits. + +@kbd{-} doesn't work when you type in the echo area, because you need to +be able to insert the @samp{-} character itself; use @kbd{M--} instead, +if you need to specify negative arguments in the echo area. +@end table + +@key{C-g} is used to abort the reading of a multi-character key +sequence, to cancel lengthy operations (such as multi-file searches) and +to cancel reading input in the echo area. + +@table @asis +@item @kbd{C-g} (@code{abort-key}) +@cindex cancelling typeahead +@cindex cancelling the current operation +@kindex C-g, in Info windows +@findex abort-key +Cancel current operation. +@end table + +The @samp{q} command of Info simply quits running Info. + +@table @asis +@item @kbd{q} (@code{quit}) +@itemx @kbd{C-x C-c} +@cindex quitting +@kindex q +@kindex C-x C-c +@findex quit +Exit GNU Info. +@end table + +If the operating system tells GNU Info that the screen is 60 lines tall, +and it is actually only 40 lines tall, here is a way to tell Info that +the operating system is correct. + +@table @asis +@item @kbd{M-x set-screen-height} +@findex set-screen-height +@cindex screen, changing the height of +Read a height value in the echo area and set the height of the +displayed screen to that value. +@end table + +On MS-DOS/MS-Windows, this command actually tries to change the +dimensions of the visible screen to the value you type in the echo +area. + +Finally, Info provides a convenient way to display footnotes which might +be associated with the current node that you are viewing: + +@table @asis +@item @kbd{ESC C-f} (@code{show-footnotes}) +@kindex ESC C-f +@findex show-footnotes +@cindex footnotes, displaying +Show the footnotes (if any) associated with the current node in +another window. You can have Info automatically display the footnotes +associated with a node when the node is selected by setting the +variable @code{automatic-footnotes}. @xref{Variables,, +@code{automatic-footnotes}}. +@end table + + +@node Variables +@chapter Manipulating Variables + +GNU Info uses several internal @dfn{variables} whose values are looked +at by various Info commands. You can change the values of these +variables, and thus change the behavior of Info, if desired. + +There are three ways to set the value of a variable, listed here in +order of precedence: + +@enumerate +@item +interactively, using the @code{set-variable} command described below; +@item +on the command line, using the @option{-v} (@option{--variable}) +command line option (@pxref{variable-assignment}); +@item +in the @code{#var} section of the @code{.infokey} file (@pxref{Custom +Key Bindings}). +@end enumerate + +@table @asis +@item @kbd{M-x set-variable} +@cindex variables, setting +@findex set-variable +Read the name of a variable, and the value for it, in the echo area +and then set the variable to that value. Completion is available when +reading the variable name (@pxref{The Echo Area}); completion is also +available when reading the value when that makes sense. + +@item @kbd{M-x describe-variable} +@cindex variables, describing +@findex describe-variable +Read the name of a variable in the echo area and display its value and +a brief description. +@end table + +Here is a list of the variables that you can set in Info. + +@vtable @code +@item automatic-footnotes +@cindex @code{*Footnotes*} window +@cindex footnotes window +When set to @code{On}, footnotes appear and disappear automatically; +else, they appear at the bottom of the node text. This variable is +@code{Off} by default. When a node is selected, a window containing +the footnotes which appear in that node is created, and the footnotes +are displayed within the new window. The window that Info creates to +contain the footnotes is called @code{*Footnotes*}. If a node is +selected which contains no footnotes, and a @code{*Footnotes*} window +is on the screen, the @code{*Footnotes*} window is deleted. Footnote +windows created in this fashion are not automatically tiled so that +they can use as little of the display as is possible. + +@item automatic-tiling +When set to @code{On}, creating or deleting a window resizes other +windows. This variable is @code{Off} by default. Normally, typing +@samp{C-x 2} divides the current window into two equal parts. When +@code{automatic-tiling} is set to @code{On}, all of the windows are +resized automatically, keeping an equal number of lines visible in +each window. Any @code{*Completions*} and @code{*Footnotes*} windows +are exceptions to the automatic tiling; they retain their original +size. + +@anchor{cursor-movement-scrolls} +@item cursor-movement-scrolls +When set to @code{On}, when cursor movement commands reach the +top or bottom of a node, another node is loaded depending on the +value of @code{scroll-behavior} (see below). This is the default. +When this variable is set to @code{Off}, cursor movements stop at the +top or bottom of a node. + +@item errors-ring-bell +When set to @code{On} (the default), errors cause the bell to ring. + +@item follow-strategy +When set to @code{remain} (the default), Info tries to remain within the +directory containing the currently displayed Info file when following a +cross-reference to an external manual, before looking for the referenced +manual in the search path. The alternative value is @code{path}, which +means to look through the search path right away. + +@code{remain} is intended to be useful for several Texinfo manuals that +all reference each other and whose versions should match each other. +(For example, various manuals relating to a particular version of +Emacs.) + +The alternative behavior, with @code{path}, may be useful when your +Info file search path parallels your command shell's search path, and +you always want to find documentation of the version of the program that +the shell would execute. + +@item gc-compressed-files +When set to @code{On}, Info garbage collects files which had to be +uncompressed. The default value of this variable is @code{Off}. +Whenever a node is visited in Info, the Info file containing that node +is read into memory, and Info reads information about the tags and +nodes contained in that file. Once the tags information is read by +Info, it is never forgotten. However, the actual text of the nodes +does not need to be retained unless a particular Info window needs it. +For non-compressed files, node text is not remembered when it is no +longer in use. But de-compressing a file can be a time-consuming +operation, and so Info tries hard not to do it twice. This variable +tells Info it is okay to garbage collect the text of the nodes of a +file which was compressed on disk. + +@item hide-note-references +By default, Info displays the contents of Info files mostly verbatim, +including text that is used by Info readers for navigation (for example, +marking the location of menus or cross-references). If you set this +variable to @code{On}, some of this text is hidden, in a similar way to +the @code{Info-hide-note-references} variable in Emacs +(@pxref{Emacs Info Variables, , , info, Info}). + +@item highlight-searches +When set to @code{On}, highlight matches from searching commands +(@pxref{Searching Commands}). + +@item infopath-no-defaults +@anchor{infopath-no-defaults} +Used in conjunction with the @env{INFOPATH} environment variable +(@pxref{INFOPATH}). When set to @code{On}, the default documentation +directory defined when Info was built (e.g., @file{/usr/share/info}) +is not added to the search path for Info files. + +@item ISO-Latin +@cindex ISO Latin characters +@cindex Meta key sets eighth bit +The default is @code{On}, which means that Info accepts and displays +characters represented by bytes with values 128 and above, such as +characters in the UTF-8 encoding or in various 8-bit ISO Latin +characters, as well as allowing you to input such characters. + +The only reason to set this variable to @code{Off} would be if your +terminal set the eighth bit of a byte to represent the Meta key being +pressed. + +@item key-time +@cindex slow network connections +Length of time in milliseconds to wait for the next byte of a byte +sequence generated by a key (or key chord) on the keyboard. For +example, if the @kbd{down} key generates the byte sequence +@kbd{@key{ESC} O B}, and the two bytes @kbd{@key{ESC} O} have been +received, then a @kbd{B} byte would have to be received within this +length of time for a key press of @kbd{down} to be registered. You +may wish to set this variable to a larger value for slow terminals or +network connections. + +If you set this variable to 0, it's unspecified whether a recognized +byte sequence representing a key takes precedence over another +recognized sequence representing a key that is an initial subsequence of +the first sequence. In some cases, you may be able to make pressing a +special key on the keyboard that Info doesn't know about (for example, a +function key) cause a command to be executed by setting this variable to +0, and giving the byte sequence the key sends in @file{.infokey}. +(@xref{Custom Key Bindings}.) + +@anchor{min-search-length} +@item min-search-length +Minimum length of a search string (default 1). Attempts to initiate a +search for a string (or regular expression) shorter than this value, +result in an error. + +@item mouse +What method to use to get input from a mouse device. The default value is +@samp{Off}. Set this variable to @code{normal-tracking} to make Info use +``normal tracking mode'' if it detects that the terminal supports it. This +enables you to scroll the contents of the active window with a mouse +scrollwheel. + +@cindex Selecting text with the mouse +@cindex xterm mouse selections +On terminal emulators running under the X Window System, such as +@command{xterm}, you can usually select text with the mouse. However, +mouse tracking mode may interfere with this. When this happens, you may +be able to select text by holding down the @kbd{Shift} key while +clicking and dragging. + +@item nodeline +@cindex node header line +How to print the node header line that appears at the top of each node. +By default only the pointers to neighbouring nodes are displayed +(the ``Next'', ``Prev'', and ``Up'' pointers): this corresponds to +the @code{pointers} value for this variable. To print the entire line, +set @code{nodeline} to the value @code{print}, which will include the +filename and name of the node. To not display the header line at all, +use the value @code{no}. + +@anchor{scroll-behavior} +@item scroll-behavior +@itemx scroll-behaviour +The two variable names are synonymous. Control what happens when +scrolling commands are used at the end or beginning of a node +(@pxref{Scrolling Commands}). The default value for this variable is +@code{Continuous}. Possible values: + +@table @code +@item Continuous +Try to get the first item in this node's menu, or failing that, the +@samp{Next} node, or failing that, the @samp{Next} of the @samp{Up} +node. This behavior is identical to using the @samp{]} +(@code{global-next-node}) and @samp{[} (@code{global-prev-node}) +commands. + +@item Next Only +Only try to get the @samp{Next} node. + +@item Page Only +Just stop, changing nothing. With this value, no scrolling command +can change the node that is being viewed. +@end table + +This variable also affects cursor movement commands (@pxref{Cursor +Commands}) unless the @code{cursor-movement-scrolls} variable is set to +@code{Off}. @xref{cursor-movement-scrolls}. + +@item scroll-last-node +Control what happens when a scrolling command is issued at the end of +the last node. Possible values are: + +@table @code +@item Stop +Do not scroll. Display the @samp{No more nodes within this document} +message. This is the default. + +@item Top +Go to the top node of the document. +@end table + +This variable is in effect only if @code{scroll-behavior} is set to +@code{Continuous}. + +@item scroll-step +The number of lines to scroll to bring the cursor back into the window. +The default value of this variable is 1, which causes a kind of ``smooth +scrolling'' which some people prefer. Scrolling happens automatically +if the cursor has moved out of the visible portion of the node text. + +If the variable @code{scroll-step} is 0, the cursor (and the +text it is attached to) is placed in the centre of the window. + +@item search-skip-screen +Set the starting point of repeated searches (@pxref{repeated-search}). +When set to @code{Off} (the default), repeated searches start at the +position immediately following (when searching in forward direction), +or immediately preceding (when searching backwards) the cursor. When +set to @code{On}, repeated searches omit lines visibly displayed on +the screen. In other words, forward searches (@kbd{@}}) start at the +beginning of the next page, and backward searches (@kbd{@{}) start at +the end of the previous page. + +@item show-index-match +When set to @code{On} (the default), the portion of the matched search +string that you typed is indicated (by displaying it in the +``opposite'' case) in the result message (@pxref{Searching Commands,, +@code{next-index-match}}). + +@item visible-bell +When set to @code{On}, Info attempts to flash the screen instead of +ringing the bell. This variable is @code{Off} by default. If the +terminal does not allow flashing, this variable has no effect. (But +you can still make Info perform quietly by setting the +@code{errors-ring-bell} variable to @code{Off}; or using an external +command to mute the bell, e.g., @code{xset b 0 0 0}.) + +@end vtable + + +@node Colors and Styles +@chapter Colors and Styles + +You can choose to highlight parts of Info's display, such as +cross-references and search matches, using a variety of styles, +including colors, boldface and underline. Here are the variables that +are available to do this: + +@vtable @code +@item link-style +Used for cross-references and menu entries. + +@item active-link-style +Used for a cross-reference or menu entry when typing @key{RET} would +have the effect of following said cross-reference or menu entry. + +@item match-style +Used for matches from a search command. (@xref{Searching Commands}.) +@end vtable + +Each of these is given in the @file{.infokey} file just as the variables +in the previous chapter. Their values are a comma-separated list of +values in the following table: + +@table @code +@item black +@itemx red +@itemx green +@itemx yellow +@itemx blue +@itemx magenta +@itemx cyan +@itemx white +@cindex Colored foreground +Use the color specified for text. + +@item nocolor +@itemx nocolour +Turn off any color that was in effect, using the terminal's default color. + +@item bgblack +@itemx bgred +@itemx bggreen +@itemx bgyellow +@itemx bgblue +@itemx bgmagenta +@itemx bgcyan +@itemx bgwhite +@cindex Colored background +Use the color specified for the background. + +@item bgnocolor +@itemx bgnocolour +Use the terminal's default background color. + +@item underline +@itemx nounderline +@cindex Underlined text +Turn text underline on or off. + +@item standout +@itemx nostandout +Turn `standout mode' on or off. Standout mode entails the use of appearance +modes that make text stand out, and varies between terminals. + +@item bold +@itemx regular +@itemx nobold +@cindex Bold text +Turn boldface on or off. + +@item blink +@itemx noblink +@cindex Blinking text +Make the text blink, or not. + +@end table + +Here is an sample excerpt from an @file{.infokey} file: + +@example +#var +link-style=yellow +active-link-style=yellow,bold +match-style=underline,bold,nocolor +@end example + +@noindent With this, cross-references are all yellow, and active +cross-references are additionally displayed in bold. Any search +matches will be shown in bold, and underlined. Moreover, if there is a +search match inside a cross-reference, the @samp{nocolor} rendition +style will cancel the yellow color, leaving the text in the match the +terminal's default color. (Note, however, that the rendition styles for +active cross-references take priority over those for search matches, +so search matches there will still be displayed in yellow.) + + +@node Custom Key Bindings +@chapter Customizing Key Bindings and Variables + +@cindex default key bindings, overriding +@cindex overriding default key bindings +@cindex customizing key bindings +@cindex key bindings, customizing +@cindex @command{infokey}, program for customizing key bindings +@cindex @file{_info} file (MS-DOS) + +Info allows you to override the default key-to-command bindings and +variable settings described in this document. (The @option{--vi-keys} +option rebinds many keys at once; @pxref{--vi-keys}.) + +On startup, GNU Info looks for a configuration file in the invoker's +@env{HOME} directory called @file{.infokey}, i.e., +@file{~/.infokey}.@footnote{Due to the limitations of DOS filesystems, +the MS-DOS version of Info looks for a file @file{_infokey} instead. If +the @env{HOME} variable is not defined, Info additionally looks in the +current directory.} If it is present, then Info adopts the key bindings +and variable settings contained therein. To use an alternative +configuration file, use the @option{--init-file} option +(@pxref{--init-file}). + +Variables may also be set on the command line with the +@option{--variable} option (@pxref{variable-assignment}). Variable +settings on the command line override settings from the @file{.infokey} +file. + +@menu +* @t{infokey} format:: +@end menu + +@node @t{infokey} format +@section @command{infokey} format + +@cindex @command{infokey} format +@cindex @file{.infokey} format +@cindex format of @file{.infokey} + +Here is an example @file{.infokey} file which specifies the key +bindings that are activated by the @option{--vi-keys} option to Info +(@pxref{--vi-keys}). + +@example +#info +g first-node +G last-node +\mb beginning-of-node +\me end-of-node +j next-line +k prev-line + +f scroll-forward-page-only +^f scroll-forward-page-only +\m\ scroll-forward-page-only +z scroll-forward-page-only-set-window + +b scroll-backward-page-only +^b scroll-backward-page-only +w scroll-backward-page-only-set-window + +\kd down-line +^e down-line +^j down-line +^m down-line +\ku up-line +^y up-line +^k up-line + +d scroll-half-screen-down +^d scroll-half-screen-down +u scroll-half-screen-up +^u scroll-half-screen-up + +^xn next-node +^xp prev-node +^xu up-node +' last-node +\mt top-node +\md dir-node + +^xg goto-node +I goto-invocation-node + +n search-next +N search-previous + +\mf xref-item +^xr xref-item + +\mg select-reference-this-line +^x^j select-reference-this-line +^x^m select-reference-this-line + +^c abort-key + +\mh get-info-help-node + +:q quit +ZZ quit + +#echo-area +\mh echo-area-backward +\ml echo-area-forward +\m0 echo-area-beg-of-line +\m$ echo-area-end-of-line +\mw echo-area-forward-word +\mx echo-area-delete +\mu echo-area-abort +^v echo-area-quoted-insert +\mX echo-area-kill-word +@end example + +The file consists of one or more @dfn{sections}. Each section starts with +a line that identifies the type of section. The possible sections are: + +@table @code +@item #info +Key bindings for Info windows. +The start of this section is indicated by a line containing just +@code{#info} by itself. If this is the first section in the source +file, the @code{#info} line can be omitted. The rest of this section +consists of lines of the form: + +@example +@var{string} whitespace @var{action} [ whitespace [ # comment ] ] newline +@end example + +Whitespace is any sequence of one or more spaces and/or tabs. Comment +is any sequence of any characters, excluding newline. @var{string} is +the key sequence which invokes the action. @var{action} is the name of +an Info command. The characters in @var{string} are interpreted +literally or prefixed by a caret (@code{^}) to indicate a control +character. A backslash followed by certain characters specifies input +keystrokes as follows: + +@table @code +@item \b +Backspace +@item \e +Escape (ESC) +@item \n +Newline +@item \r +Return +@item \t +Tab +@item \ku +Up arrow +@item \kd +Down arrow +@item \kl +Left arrow +@item \kr +Right arrow +@item \kU +Page Up +@item \kD +Page Down +@item \kh +HOME +@item \ke +END +@item \kx +Delete (DEL) +@item \m@var{x} +Meta-@var{x} where @var{x} is any character as described above. +@end table + +Backslash followed by any other character indicates that character is to +be taken literally. Characters which must be preceded by a backslash +include caret, space, tab, and backslash itself. + +@item #echo-area +Key bindings for the echo area. +The start of this section is indicated by a line containing just +@code{#echo-area} by itself. The rest of this section has a syntax +identical to that for the key definitions for the Info area, described +above. + +@item #var +Variable initializations. The start of this section is indicated by a +line containing just @code{#var} by itself. Following this line is a +list of variable assignments, one per line. Each line consists of a +variable name (@pxref{Variables}) followed by @code{=} followed by a +value. There may be no white space between the variable name and the +@code{=}, and all characters following the @code{=}, including white +space, are included in the value. +@end table + +Blank lines and lines starting with @code{#} are ignored, except for +the special section header lines. + +Key bindings defined in the @file{.infokey} file take precedence over GNU +Info's default key bindings, whether or not @samp{--vi-keys} is used. A +default key binding may be disabled by overriding it in the @file{.infokey} +file with the action @code{invalid}. In addition, @emph{all} default +key bindings can be disabled by adding this line @emph{anywhere} in the +relevant section: + +@example +#stop +@end example + +This will cause GNU Info to ignore all the default key commands for that +section. + +Beware: @code{#stop} can be dangerous. Since it disables all default +key bindings, you must supply enough new key bindings to enable all +necessary actions. Failure to bind any key to the @code{quit} command, +for example, can lead to frustration. + +The order in which key bindings are defined in the @file{.infokey} file is +not important, except that the command summary produced by the +@code{get-help-window} command only displays the @emph{first} key that +is bound to each command. + + +@node Index +@appendix Index + +@printindex cp + +@bye diff --git a/macros/texinfo/texinfo/doc/refcard/Makefile b/macros/texinfo/texinfo/doc/refcard/Makefile new file mode 100644 index 0000000000..6fd15e80ca --- /dev/null +++ b/macros/texinfo/texinfo/doc/refcard/Makefile @@ -0,0 +1,48 @@ +# $Id: Makefile,v 1.4 2012-09-21 17:40:44 karl Exp $ +# Makefile for texinfo/doc/refcard. +# This is not hooked into Automake, just conveniences for working on the +# refcard. +# +# Copyright 2008, 2012, 2014, 2015 Free Software Foundation, Inc. +# +# This file is free software; as a special exception the author gives +# unlimited permission to copy and/or distribute it, with or without +# modifications, as long as this notice is preserved. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the +# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +doc = txirefcard + +# parallel makes, etc., will fail. +all: $(doc).pdf $(doc)-a4.pdf + +# trying to get it work with pdftex isn't worth the trouble. +$(doc).pdf: $(doc).tex + tex '\nonstopmode \input $(doc)' + dvips -t landscape -t letter $(doc) -o + ps2pdf $(doc).ps + +$(doc)-a4.pdf: $(doc).tex + tex '\nonstopmode \let\afour=1 \input $(doc)' + dvips -t landscape -t a4 $(doc) -o + ps2pdf $(doc).ps $@ + +check: ccheck vcheck + +ccheck: + ./txicmdcheck $(txi_check_args) + +vcheck: + ./txivarcheck $(txi_check_args) + +spell: + aspell list --mode=tex --add-extra-dicts=`pwd`/refcard.spell \ + < $(doc).tex | sort -f -u + +clean: + rm -f $(doc)*.dvi $(doc)*.log $(doc)*.ps + +distclean: clean + rm -f $(doc)*.pdf diff --git a/macros/texinfo/texinfo/doc/refcard/txicmdcheck b/macros/texinfo/texinfo/doc/refcard/txicmdcheck new file mode 100644 index 0000000000..3d919a152b --- /dev/null +++ b/macros/texinfo/texinfo/doc/refcard/txicmdcheck @@ -0,0 +1,239 @@ +#!/usr/bin/env perl +# $Id$ +# Copyright 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015 +# Free Software Foundation, Inc. +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, +# or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <http://www.gnu.org/licenses/>. +# +# Original author: Karl Berry. +# +# Kludge of a script to check command lists in refcard vs. refman vs. +# tp for consistency. + +exit (&main ()); + +sub main { + my $no_common = $ARGV[0] eq "--no-common"; + + my %card_cmds = &read_refcard ("txirefcard.tex"); + my %idx_cmds = &read_refidx ("../texinfo.texi"); + my %man_cmds = &read_refman ("../texinfo.texi"); + my %tp_cmds = &read_tp ("../../util/txicmdlist"); + + # find the commands that are covered everywhere. + my @found = (); + for my $cc (keys %card_cmds) { + if (exists $idx_cmds{$cc} + && exists $man_cmds{$cc} + && exists $tp_cmds{$cc}) { + push (@found, $cc); + delete $card_cmds{$cc}; + delete $idx_cmds{$cc}; + delete $man_cmds{$cc}; + delete $tp_cmds{$cc}; + } + } + + printf (" common %d: @{[sort @found]}\n", @found + 0) + unless $no_common; + + # there are numerous @findex entries which are not @-commands, which + # can be seen this way: + #my @idx_only = keys %idx_cmds; + #printf "findex only %s: @{[sort @idx_only]}\n", @idx_only + 0; + # + # let's not report those, but we do want to report normal commands that + # did not have findex entries: those which are present in all the + # other lists. + my @idx_missing = (); + for my $cc (sort keys %card_cmds) { + if (exists $man_cmds{$cc} && exists $tp_cmds{$cc}) { + push (@idx_missing, $cc); + delete $card_cmds{$cc}; + delete $man_cmds{$cc}; + delete $tp_cmds{$cc}; + } + } + printf "findex missing %s: @idx_missing\n", @idx_missing + 0 + if @idx_missing; + + # now report on commands only in some other subset. + my @card_only = keys %card_cmds; + printf "refcard only %s: @{[sort @card_only]}\n", @card_only + 0; + + my @man_only = keys %man_cmds; + printf "refman only %s: @{[sort @man_only]}\n", @man_only + 0; + + my @tp_only = keys %tp_cmds; + printf "tp only %s: @{[sort @tp_only]}\n", @tp_only + 0; + + return @card_only + @man_only + @tp_only; +} + + +# Return command names from the reference card as the keys of a hash +# (with empty values). In principle it's a list, but as a practical +# matter we want to work with a hash anyway, so we might as well return +# it that way in the first place. (Ditto for the other functions.) +# +sub read_refcard { + my ($fname) = @_; + my @ret = (); + + local *FILE; + $FILE = $fname; + open (FILE) || die "open($FILE) failed: $!"; + while (<FILE>) { + next unless /^\\txicmd/; + chomp; + my $xcmd = 0; + s/\\txicmdarg\{.*?\}\}?//; # first get rid of the arguments + s/\}\{.*//; # then the descriptions + s/^\\txicmdx\{// && ($xcmd = 1); # used for the @def...x + s/^\\txicmd\{//; # finally the markup cmd itself + s/\\ttbraced\{\}//g; # quote cmd list + + my (@cmds) = split (/,? +/, $_); # occasionally we combine cmds + + # we typeset these specially in TeX. + if ("@cmds" eq "@#1footing") { + @cmds = ('@oddfooting', '@evenfooting', '@everyfooting'); + } elsif ("@cmds" eq "@#1heading") { + @cmds = ('@oddheading', '@evenheading', '@everyheading'); + } + + # add each command from this line to the return. + for my $c (@cmds) { +#warn "refcard $c\n"; +#warn "refcard $c{x}\n" if $xcmd; + next if $c eq "txicommandconditionals"; # variable not separate in manual + if ($c eq '@\tildechar') { # TeX specialties, forcibly make them match + $c = '@~'; + } elsif ($c eq '@\var{whitespace}') { + $c = '@var{whitespace}'; + } + $c = '@~' if $c eq '@\tildechar'; # TeX + $c = '@\\' if $c eq '@\bschar'; # TeX + $c = '@{' if $c eq '@\lbracechar'; # TeX + $c = '@}' if $c eq '@\rbracechar'; # TeX + $c = '@&' if $c eq '@\&'; # TeX + push (@ret, $c); + push (@ret, "${c}x") if $xcmd; + } + } + push (@ret, '@end', '@uref', '@appendixsection'); # described in text + push (@ret, '@,'); # our non-parsing above lost these + push (@ret, qw(@atchar @ampchar @lbracechar @rbracechar @backslashchar)); + close (FILE) || warn "close($FILE) failed: $!"; + + my %ret; @ret{@ret} = (); + return %ret; +} + + +# Return command names from @findex entries in the reference manual as +# the keys of a hash (empty values). +# +sub read_refidx { + my ($fname) = @_; + my @ret = (); + + local *FILE; + $FILE = $fname; + open (FILE) || die "open($FILE) failed: $!"; + while (<FILE>) { + next unless s/^\@findex\s+//; # only consider @findex lines + chomp; + s/\s+\@r.*$//;# if /^[^a-zA-Z]/; # remove comment + s/\@\{\@\}//; # remove @{@} used in atchar, etc. + s/<colon>/:/; # @: + s/<newline>/var{whitespace}/; # special generic entry: @var{whitespace} + s/^/\@/ unless /^\@/; # prepend @ unless already there (@@ @{ @}) + push (@ret, $_); + } + close (FILE) || warn "close($FILE) failed: $!"; + + my %ret; @ret{@ret} = (); + return %ret; +} + + +# Return command names from the @-Command List node in the reference +# manual as the keys of a hash (empty values). +# +sub read_refman { + my ($fname) = @_; + my @ret = (); + + local *FILE; + $FILE = $fname; + open (FILE) || die "open($FILE) failed: $!"; + while (<FILE>) { + last if /^\@section \@\@-Command List/; # ignore until right section + } + while (<FILE>) { + last if /^\@end table/; # ignore again after the summary + next unless s/^\@itemx? *\@//; # only want item[x]s in the table + chomp; + s/\@\{.+//; # remove braced arguments (but not @{) + s/ .*//; # remove arguments following a space + s/\@\@/@/g; # @@ -> @ + next if $_ =~ /^\@(br|ctrl)$/; # @ignore-d in text + push (@ret, $_); + } + push (@ret, '@{'); # our non-parsing above fails on this one + close (FILE) || warn "close($FILE) failed: $!"; + + my %ret; @ret{@ret} = (); + return %ret; +} + + +# Return command names implemented in the general parser as the keys of +# a hash (empty values). The argument is the command to run to return +# the list. +# +sub read_tp { + my ($prog) = @_; + my @ret = (); + + local *FILE; + $FILE = "$prog |"; + open (FILE) || die "open($FILE) failed: $!"; + while (<FILE>) { + chomp; + # excise @<whitespace> commands from normal list. + next if $_ eq '@ ' || $_ eq "\@\t" || $_ eq "" || $_ eq '@'; + + # obsolete and/or subsidiary commands we don't want to document as usual. + next if $_ =~ /allow-recursion + |columnfractions + |cropmarks + |ctrl + |(even|every|odd)(foot|head)ingmarks + |quote-arg + |rmacro + |set(short)?contentsaftertitlepage + |shorttitle$ + |\| + /x; + push (@ret, $_); + } + close (FILE) || warn "close($FILE) failed: $!"; + + push (@ret, '@var{whitespace}'); + + my %ret; @ret{@ret} = (); + return %ret; +} diff --git a/macros/texinfo/texinfo/doc/refcard/txirefcard-a4.pdf b/macros/texinfo/texinfo/doc/refcard/txirefcard-a4.pdf Binary files differnew file mode 100644 index 0000000000..4662d54418 --- /dev/null +++ b/macros/texinfo/texinfo/doc/refcard/txirefcard-a4.pdf diff --git a/macros/texinfo/texinfo/doc/refcard/txirefcard.pdf b/macros/texinfo/texinfo/doc/refcard/txirefcard.pdf Binary files differnew file mode 100644 index 0000000000..3682a96844 --- /dev/null +++ b/macros/texinfo/texinfo/doc/refcard/txirefcard.pdf diff --git a/macros/texinfo/texinfo/doc/refcard/txirefcard.tex b/macros/texinfo/texinfo/doc/refcard/txirefcard.tex new file mode 100644 index 0000000000..fa88c2b5e5 --- /dev/null +++ b/macros/texinfo/texinfo/doc/refcard/txirefcard.tex @@ -0,0 +1,996 @@ +% Texinfo reference card. +% $Id$ +% +%**start of header +% This file can be printed with 1, 2, or 3 columns per page (see below). +% Specify how many you want here. (Except only 3 has been tested.) +\newcount\columnsperpage +\columnsperpage=3 + +% Set letterpaper to 0 for A4 paper, 1 for letter (US) paper. +% (Except only 1 (letter) has been tested) +% Useful only when columnsperpage is 2 or 3. +% \afour is defined in the invocation from the Makefile. +\newcount\letterpaper +\ifx\undefined\afour\letterpaper=1 \else\letterpaper=0 \fi + +% Copyright 2008-2019 Free Software Foundation, Inc. +% +% This file is part of GNU Texinfo. +% +% Texinfo 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. +% +% Texinfo 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 Texinfo. If not, see <http://www.gnu.org/licenses/>. +% +% This file is written in plain TeX. +% +% To compile and print this document: +% tex refcard.tex +% dvips -t letter -t landscape refcard.dvi +% +% Author: +% Robert D. Solimeno (adapted from Emacs reference card by Stephen Gildea) +% Internet: solimeno (at) gmail (dot) com +% +% The author thanks Karl Berry for the opportunity to contribute to this +% project and for his assistance and great patience as I learned how to +% use TeX. +% +% Much of the text is based on, and sometimes copied from, the @-Command +% Summary node in the Texinfo manual, originally written by Bob Chassell. + +\def\versionyear{2019} % year manual was updated +\def\versionTexinfo{6.6} % version of Texinfo this manual is for + +\def\copyrightnotice{% +\vskip 1ex plus 1filll\begingroup\small +\advance\baselineskip by 1pt +\centerline{Copyright \copyright\ 2019 Free Software Foundation, Inc.} +\centerline{for Texinfo version \versionTexinfo, \versionyear} +\centerline{by Robert D. Solimeno} +\centerline{and the Texinfo maintainers} + +\smallskip + Copying and distribution of this material, with or without modification, + are permitted in any medium without royalty provided the copyright + notice and this notice are preserved. + +\smallskip +For printed copies of the Texinfo manual, visit {\tt +http://www.gnupress.org} or write to the Free Software Foundation, Inc., +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +\endgroup} + +% make \bye not \outer so that the \def\bye in the \else clause below +% can be scanned without complaint. +\def\bye{\par\vfill\supereject\end} + +\newdimen\intercolumnskip %horizontal space between columns +\newbox\columna %boxes to hold columns already built +\newbox\columnb + +\def\ncolumns{\the\columnsperpage} + +\message{[\ncolumns\space + column\if 1\ncolumns\else s\fi\space per page]} + +\def\scaledmag#1{ scaled \magstep #1} + +% This multi-way format was designed by Stephen Gildea October 1986. +% Note that the 1-column format is fontfamily-independent. +\ifnum \ncolumns=1 %one-column format uses normal size + \hsize 4in + \vsize 10in + \voffset -.7in + \font\titlefont=\fontname\tenbf \scaledmag3 + \font\headingfont=\fontname\tenbf \scaledmag2 + \font\smallfont=\fontname\sevenrm + \font\smallsy=\fontname\sevensy + \font\acrofont=cmr9 + \footline{\hss\folio} + \def\makefootline{\baselineskip10pt\hsize6.5in\line{\the\footline}} +\else %2 or 3 columns uses prereduced size + \hsize 3.4in + \ifnum \letterpaper=1 + \vsize 7.95in + \else + \vsize 7.65in + \fi + \hoffset -.75in + \voffset -.745in + \font\titlefont=cmbx8 \scaledmag3 + \font\headingfont=cmbx8 \scaledmag2 + \font\subheadingfont=cmbx8 \scaledmag1 + \font\subsubheadingfont=cmbx8 \scaledmag0 + \font\smallfont=cmr8 + \font\smallsy=cmsy8 + \font\eightrm=cmr8 + \font\eightbf=cmbx8 + \font\eightit=cmti8 + \font\eighttt=cmtt8 + \font\eightmi=cmmi8 + \font\eightsl=cmsl8 + \font\eightsy=cmsy8 + \textfont0=\eightrm + \textfont1=\eightmi + \textfont2=\eightsy + \def\rm{\eightrm} + \def\bf{\eightbf} + \def\it{\eightit} + \def\sl{\eightsl} + \def\tt{\eighttt} + \font\acrofont=cmr7 + \ifnum \letterpaper=1 + \normalbaselineskip=.75\normalbaselineskip + \else + \normalbaselineskip=.7\normalbaselineskip + \fi + \normallineskip=.8\normallineskip + \normallineskiplimit=.8\normallineskiplimit + \normalbaselines\rm %make definitions take effect + + \if 2\ncolumns + \let\maxcolumn=b + \footline{\hss\rm\folio\hss} + \def\makefootline{\vskip 2in \hsize=6.86in\line{\the\footline}} + \else \if 3\ncolumns + \let\maxcolumn=c + \nopagenumbers + \else + \errhelp{You must set \columnsperpage equal to 1, 2, or 3.} + \errmessage{Invalid number of columns per page} + \fi\fi + + \intercolumnskip=.1in + \def\abc{a} + \output={% %see The TeXbook page 257 + % This next line is useful when designing the layout. + %\immediate\write16{Column \folio\abc\space starts with \firstmark} + \if \maxcolumn\abc \multicolumnformat \global\def\abc{a} + \else\if a\abc + \global\setbox\columna\columnbox \global\def\abc{b} + %% in case we never use \columnb (two-column mode) + \global\setbox\columnb\hbox to -\intercolumnskip{} + \else + \global\setbox\columnb\columnbox \global\def\abc{c}\fi\fi} + \def\multicolumnformat{\shipout\vbox{\makeheadline + \hbox{\box\columna\hskip\intercolumnskip + \box\columnb\hskip\intercolumnskip\columnbox} + \makefootline}\advancepageno} + \def\columnbox{\leftline{\pagebody}} + + \def\bye{\par\vfill\supereject + \if a\abc \else\null\vfill\eject\fi + \if a\abc \else\null\vfill\eject\fi + \end} +\fi + +\parindent 0pt +\parskip 1ex plus.5ex minus.5ex % between entries +\emergencystretch = .9\hsize +\rightskip = 0pt plus.33\hsize +\hbadness = 3000 + +% characters special to TeX. +\catcode`\^=12 +\catcode`\_=12 +\def\tildechar{{\tt \char`\~}} +\def\bschar{{\tt \char`\\}} +\def\lbracechar{{\tt \char`\{}} +\def\rbracechar{{\tt \char`\}}} + +\def\small{\smallfont\textfont2=\smallsy\baselineskip=0.9\baselineskip} + +% newcolumn - force a new column. Use sparingly if at all. +\outer\def\newcolumn{\vfill\eject} + +% title - page title. Argument is title text. +\outer\def\title#1{{\titlefont\centerline{#1}}\vskip 1ex plus .5ex minus .75ex} + +% chapter - new major section. Argument is section name. +\outer\def\chapter#1{\glueabove{2ex plus1.5ex minus1.5ex}% + \nobreak\noindent {\headingfont #1}% + \nobreak\vskip 0pt plus1ex\nobreak} +% +\outer\def\section#1{\glueabove{1.5ex plus1ex minus1ex} + \nobreak\noindent {\subheadingfont #1}% + \nobreak\vskip 0pt plus.5ex\nobreak} +% +\outer\def\subsection#1{\glueabove{.75ex plus.5ex minus.5ex}% + \nobreak\noindent \centerline{\it #1}% + \nobreak\vskip-.5ex % reduce parskip + \nobreak + } + +\def\glueabove#1{\par\ifnum\lastpenalty<10000 \filbreak \vskip #1\relax\fi} + +% paralign - begin paragraph containing an alignment. +% If an \halign is entered while in vertical mode, a parskip is never +% inserted. Using \paralign instead of \halign solves this problem. +\def\paralign{\vskip\parskip\halign} + +% forced line break. +\def\linebreak{\hfil\break} + +% code, samp - typewriter, without or with surrounding quotes. +\def\code#1{{\tt#1}\null} %\null so not an abbrev even if period follows +\def\samp#1{`\code{#1}'} + +% var - metasyntactic var, in slanted. +\def\var#1{{\sl#1\/}\null} + +% acro - one point size smaller than main text. +\def\acro#1{{\acrofont #1}} + +% beginexample...endexample surrounds literal text, such a code example. +% typeset in a typewriter font with line breaks preserved +\def\beginexample{\par\leavevmode\begingroup + \obeylines\obeyspaces\parskip0pt\tt} +{\obeyspaces\global\let =\ } +\def\endexample{\endgroup} + +% \beginindentedkeys...\endindentedkeys - key definitions will be +% indented, but running text, typically used as headings to group +% definitions, will not. +\newdimen\keyindent +\def\beginindentedkeys{\keyindent=1em} +\def\endindentedkeys{\keyindent=0em} +\endindentedkeys + +% \key{key-name}{description of key} +% prints the description left-justified, and the key-name in a \code +% form near the right margin. Both in typewriter. The order of the +% arguments is because that is what describe-mode outputs. +\def\key#1#2{\leavevmode\hbox to \hsize{\tt + \vtop{\hsize=.75\hsize \rightskip=1em \hskip\keyindent\relax #2}% + #1\hfil}} + +% \infokey KEY DESC +% the keystroke is delimited by space(s) from the description, the idea +% being to make straight copy-and-paste from the help message mostly work. +\gdef\infokey#1 #2\cr{\code{#1}\cr}% + +% make eol active. +\def\begininfokeys{ + \smallskip + \begingroup + \def\par{\noalign{\smallskip}}% blank lines within the table + \halign\bgroup ##\quad\hfil&##\hfil\cr +} +\def\endinfokeys{\egroup\endgroup\smallskip} + +% txicmd - definition of a txicmd. +% \txicmd{cmdname}{args}{description of txicmd} +% prints the txicmd-name left-justified in typewriter, and the description +% in small font in a paragraph below the command. +% +\def\txicmd#1#2#3{\ifnum\lastpenalty<10000 \filbreak\fi + {{\tt#1}\txicmdarg{#2}\ {\small#3}\vskip -2pt}} +\def\txicmdarg#1{\ {\small\sl\kern-.17em #1}} +% the kern there gives us less than a full word space; we want enough +% space for the line-delimited commands like @chapter, but not to be +% excessive for the brace-delimited commands like @url. + +% For the definition commands, which all have @foo and @foox variants. +\def\txicmdx#1{\txicmd{#1\rmbrack[x]}} + +% Enclose argument in roman brackets. +\def\rmbrack[#1]{{\small[}#1\/{\small{]}\thinspace}} + +% Enclose argument in typewriter braces. +\def\ttbraced#1{\lbracechar#1\rbracechar} + +% metax - definition of a M-x command. +% \metax{description of command}{M-x command-name} +% Tries to justify the beginning of the command name at the same place +% as \key starts the key name. (The "M-x " sticks out to the left.) +\newbox\metaxbox +\setbox\metaxbox\hbox{\code{M-x }} +\newdimen\metaxwidth +\metaxwidth=\wd\metaxbox + +\def\metax#1#2{\leavevmode\hbox to \hsize{\hbox to .75\hsize + {\hskip\keyindent\relax#1\hfil}% + \hskip -\metaxwidth minus 1fil + \code{#2}\hfil}} + +% threecol - like "key" but with two key names. +% for example, one for doing the action backward, and one for forward. +\def\threecol#1#2#3{\hskip\keyindent\relax#1\hfil&\code{#2}\hfil\quad + &\code{#3}\hfil\quad\cr} + +% Define the LaTeX logo +\def\LaTeX{L\kern-.35em \raise.65ex\hbox{\fiverm A}\kern-.15em \TeX}% + +% Define some special glyphs, taken from Texinfo.tex +% The @error{} command. +% Adapted from the TeXbook's \boxit. +% +\newbox\errorbox +% +{\tentt \global\dimen0 = 3em}% Width of the box. +\dimen2 = .35pt % Thickness of rules +% The text. (`r' is open on the right, `e' somewhat less so on the left.) +\setbox0 = \hbox{\kern-.75pt \smallfont error\kern-1.5pt} +% +\setbox\errorbox=\hbox to \dimen0{\hfil + \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. + \advance\hsize by -2\dimen2 % Rules. + \vbox{% + \hrule height\dimen2 + \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. + \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. + \kern3pt\vrule width\dimen2}% Space to right. + \hrule height\dimen2} + \hfil} +% +\def\error{\leavevmode\lower.7ex\copy\errorbox} + +% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. +% +% Since these characters are used in examples, it should be an even number of +% \tt widths. Each \tt character is 1en, so two makes it 1em. +% +\def\point{$\star$} +\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} +\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} +\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} + +% @registeredsymbol - R in a circle. +\def\registeredsymbol{% + \raise.8ex\hbox{{{\ooalign{\hfil\raise.07ex\hbox{\fiverm R}% + \hfil\crcr\Orb}}% + }}% +} + +\def\ordf{\leavevmode\raise1ex\hbox{\fiverm \underbar{a}}} +\def\ordm{\leavevmode\raise1ex\hbox{\fiverm \underbar{o}}} + +\font\eurofont = feybr10 at 8pt +\def\euro{{\eurofont e}} + +\font\ecfont = ecrm0800 +\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}} +\def\ogonek#1{{% + \ecfont \setbox0=\hbox{#1}% + \ifdim\ht0=1ex\accent"0C #1% + \else\ooalign{\unhbox0\crcr\hidewidth\char"0C \hidewidth}% + \fi +}} +% normal quotes +\def\quoteleft{`} +\def\quoteright{'} +\def\quotedblleft{``} +\def\quotedblright{''} + +%**end of header + +% +\title{GNU Texinfo Reference Card} + +\centerline{(for Texinfo version \versionTexinfo)} +\vskip1pt +\centerline{\code{http://www.gnu.org/software/texinfo/}} + +\chapter{Texinfo document skeleton} + +Texinfo source files are plain text; standard extensions are +\samp{.texinfo}, \samp{.texi}, and \samp{.txi}. A Texinfo file must +begin with lines like this: + +{\advance\baselineskip by -3pt +\code{\bschar input texinfo}\linebreak +\code{@setfilename {\sl info-file-name}}\linebreak +\code{@settitle {\sl name-of-manual}}} + +\dots the contents of the Texinfo document, +ending with:\linebreak +\code{@bye} + + +\chapter{Texinfo @-commands} + +\section{Beginning a Texinfo document} + +The commands in this section are given approximately in the order in +which they conventionally appear. + +\txicmd{@setfilename}{info-file-name}{Provide a name to be used for the +output files. Should be the first command in the input.} +\txicmd{@settitle}{title}{Specify document \var{title}.} +\txicmd{@copying}{}{Specify copyright and licensing text. Pair with \code{@end copying}.} +\txicmd{@insertcopying}{}{Insert text defined by \code{@copying}.} + +\subsection{Internationalization} + +\txicmd{@documentencoding}{enc}{Declare the input encoding to be \var{enc}; use right after \code{@setfilename}. Default is \code{US-ASCII}; other possibilities: \code{UTF-8}, \code{ISO-8859-1}, \code{koi8-r}, \dots} +\txicmd{@documentlanguage}{LL\rmbrack[\code{_}CC]}{Declare the current language as the two-character \acro{ISO}-639 abbreviation \var{LL}, optionally followed by an underscore and a two-letter \acro{ISO} 3166 two-letter country code (\var{CC}). Default is \code{en_US}.} +\txicmd{@frenchspacing}{\code{on|off}}{Control spacing after punctuation.} + +\subsection{Info directory specifications} + +\txicmd{@dircategory}{category name}{Specify an Info directory section for this file's entries. Can be repeated. We try to follow the categories in the Free Software Directory.} +\txicmd{@direntry}{}{Begin the Info directory menu entries for this file. Pair with \tt @end direntry.} + +\subsection{\acro{HTML} document description} + +\txicmd{@documentdescription}{}{Set the document description text for \acro{HTML}; default is just the title of the document. Pair with \code{@end documentdescription}.} + +\subsection{Title pages} + +\txicmd{@shorttitlepage}{title}{Generate a minimal title page, generally for the first page of output in a long printed manual.} +\txicmd{@center}{line-of-text}{Center \var{line-of-text}, usually for titles.} +\txicmd{@titlefont}{\ttbraced{\var{text}}}{In a printed manual, print \var{text} in a larger than normal font. Ignored in Info.} +\txicmd{@titlepage}{}{Begin the title page. Write the command on a line of its own, paired with \code{@end titlepage}. Ignored in Info.} +\txicmd{@title}{title}{Within \code{@titlepage}, display \var{title} appropriately.} +\txicmd{@subtitle}{subtitle}{Within \code{@titlepage}, display \var{subtitle}.} +\txicmd{@author}{author}{Within \code{@titlepage}, display \var{author}.} + +\subsection{Tables of contents} + +\txicmd{@shortcontents}{}{Print a short table of contents (chapter-level entries only). Not relevant to Info.} +\txicmd{@summarycontents}{}{Synonym for \code{@shortcontents}.} +\txicmd{@contents}{}{Print a complete table of contents. Has no effect in Info, which uses menus instead.} + + +\section{Nodes} + +\txicmd{@node}{name}{Begin a new node.} +\txicmd{@top}{title}{Mark the topmost \code{@node} in the file, which +must be defined on the line immediately preceding \code{@top}. The +\var{title} is formatted as a chapter-level heading. The entire top +node, including the \code{@node} and \code{@top} lines, are normally +enclosed with \code{@ifnottex ... @end ifnottex}.} +\txicmd{@anchor}{\ttbraced{\var{name}}}{Define \var{name} as the current location, for use as a cross-reference target.} +\txicmd{@novalidate}{}{Suppress validation of node references and omit creation of auxiliary files with \TeX. Use before \code{@setfilename}.} + + +\section{Chapter structuring} + +\txicmd{@lowersections}{}{Change subsequent chapters to sections, sections to subsections, and so on.} +\txicmd{@raisesections}{}{Change subsequent sections to chapters, subsections to sections, and so on.} +\txicmd{@part}{title}{Print part page, beginning a group of chapters; included in contents.} + +\subsection{Numbered, included in contents} + +\txicmd{@chapter}{title}{Begin a numbered chapter; \var{title} appears in the table of contents.} +\txicmd{@centerchap}{title}{Like \code{@chapter}, with chapter title centered.} + +\subsection{Context-dependent, included in contents} + +\txicmd{@section}{title}{Begin a section within a chapter. Within \code{@chapter} and \code{@appendix}, the section is numbered; within \code{@unnumbered}, it is unnumbered.} +\txicmd{@subsection}{title}{Begin a subsection within a section. Same context-dependent numbering as \code{@section}.} +\txicmd{@subsubsection}{title}{Begin a numbered subsubsection within a subsection. Same context-dependent numbering as \code{@section}.} + +\subsection{Unnumbered, included in contents} + +\txicmd{@unnumbered}{title}{Begin an unnumbered chapter.} +\txicmd{@unnumberedsec}{title}{Begin an unnumbered section.} +\txicmd{@unnumberedsubsec}{title}{Begin an unnumbered subsection.} +\txicmd{@unnumberedsubsubsec}{title}{Begin an unnumbered subsubsection.} + +\subsection{Lettered and numbered, included in contents} + +\txicmd{@appendix}{title}{Begin an appendix.} +\txicmd{@appendixsec}{title}{Begin an appendix section within an appendix; \code{@appendixsection} is a synonym.} +\txicmd{@appendixsubsec}{title}{Begin an appendix subsection; \code{@appendixsubsection} is a synonym.} +\txicmd{@appendixsubsubsec}{title}{Begin an appendix subsubsection; \code{@appendixsubsubsection} is a synonym.} + +\subsection{Unnumbered, not in contents, no new page} + +\txicmd{@chapheading}{title}{Print an unnumbered chapter-like heading.} +\txicmd{@majorheading}{title}{Like \code{@chapheading}, but generate additional vertical whitespace before the heading.} +\txicmd{@heading}{title}{Print an unnumbered section-like heading.} +\txicmd{@subheading}{title}{Print an unnumbered subsection-like heading.} +\txicmd{@subsubheading}{title}{Print an unnumbered subsubsection-like heading.} + + +\section{Menus} + +\txicmd{@menu}{}{Mark the beginning of a menu of nodes in Info. No effect in a printed manual. Pair with \code{@end menu}.} +\txicmd{@detailmenu}{}{Mark the (optional) detailed node listing in a master menu.} + + +\section{Cross references} + +\subsection{Within the Info system} + +\txicmd{@xref}{\ttbraced{node, \rmbrack[entry], \rmbrack[node-title], \rmbrack[info-file], \rmbrack[manual]}}{Makes a reference that starts with `See' in a printed manual. Follow command with punctuation. Only the first argument is mandatory.} +\txicmd{@pxref}{\ttbraced{node, \rmbrack[entry], \rmbrack[node-title], \rmbrack[info-file], \rmbrack[manual]}}{Like \code{@xref}, but starts with `see' instead of `See', and must be used inside parentheses.} +\txicmd{@ref}{\ttbraced{node, \rmbrack[entry], \rmbrack[node-title], \rmbrack[info-file], \rmbrack[manual]}}{Like \code{@xref}, but produces only the bare reference without `See' or `see'; must be followed by a punctuation mark.} +\txicmd{@inforef}{\ttbraced{node, \rmbrack[entry-name], info-file}}{Make a cross reference to an Info file for which there is no printed manual.} +\txicmd{@xrefautomaticsectiontitle}{\code{on|off}}{By default, use the section title instead of the node name in cross references.} + +\subsection{Outside of Info} + +\txicmd{@url}{\ttbraced{url, \rmbrack[displayed-text], \rmbrack[replacement]}}{Make a hyperlink reference to a uniform resource locator. \code{@uref} is a synonym.} +\txicmd{@cite}{\ttbraced{title}}{Indicate the name of a book or other reference that has no Info file; no hyperlink.} + + +\section{Marking text} + +\subsection{Markup for regular text} + +\txicmd{@abbr}{\ttbraced{abbreviation}}{Indicate a general abbreviation, such as `Comput.'} +\txicmd{@acronym}{\ttbraced{acronym}}{Indicate an acronym written in all capital letters, such as `\acro{NASA}'.} +\txicmd{@dfn}{\ttbraced{term}}{Indicate the introductory or defining use of a technical term.} +\txicmd{@emph}{\ttbraced{text}}{Emphasize \var{text}, by using italics where possible, and enclosing in asterisks in Info.} +\txicmd{@strong}{\ttbraced{text}}{Emphasize \var{text} even more strongly, by using bold where possible; still enclosed in asterisks in Info.} +\txicmd{@sub}{\ttbraced{text}}{Set \var{text} as a subscript.} +\txicmd{@sup}{\ttbraced{text}}{Set \var{text} as a superscript.} +\txicmd{@var}{\ttbraced{metasyntactic-variable}}{Indicate a meta variable (a name that stands for another piece of text).} + +\subsection{Markup for literal text} + +\txicmd{@code}{\ttbraced{sample-code}}{Indicate an expression, a syntactically complete token, or a program name. Unquoted in Info output.} +\txicmd{@command}{\ttbraced{command-name}}{Indicate a system command name, such as \code{ls}.} +\txicmd{@email}{\ttbraced{address, \rmbrack[displayed-text]}}{Indicate an email address.} +\txicmd{@env}{\ttbraced{environment-variable}}{Indicate an environment variable name, such as \code{PATH}.} +\txicmd{@file}{\ttbraced{filename}}{Indicate the name of a file, buffer, node, directory, etc.} +\txicmd{@indicateurl}{\ttbraced{url}}{Indicate a uniform resource locator, but without creating any hyperlink.} +\txicmd{@kbd}{\ttbraced{keyboard-characters}}{Indicate characters of input to be typed by users.} +\txicmd{@key}{\ttbraced{key-name}}{Indicate the name of a key on a keyboard.} +\txicmd{@option}{\ttbraced{option-name}}{Indicate a command-line option, such as \code{-v} and \code{--help}.} +\txicmd{@samp}{\ttbraced{text}}{Indicate a sequence of literal characters, in general. Quoted in Info output.} +\txicmd{@verb}{\ttbraced{delimchar literal-text delimchar}}{Output \var{literal-text}, delimited by the single character \var{delimchar}, exactly as is, including any whitespace or Texinfo special characters. Example: \code{@verb\ttbraced{|@ @\rbracechar|}}.} + +\subsection{GUI sequences} + +\txicmd{@arrow}{\ttbraced{}}{Insert a right arrow glyph, $\rightarrow$.} +\txicmd{@clicksequence}{\ttbraced{action \code{@click\ttbraced{}} \var{action} \dots}}{Represent a sequence of \acro{GUI} actions or clicks.} +\txicmd{@click}{\ttbraced{}}{Represent a single `click' in a \code{@clicksequence}.} +\txicmd{@clickstyle}{\code{@}cmd}{Execute \var{@cmd} for each \code{@click}; default is \code{@arrow}. Empty braces usually following \code{@\var{cmd}} are omitted here.} + +\subsection{Math} + +\txicmd{@math}{\ttbraced{math}}{Format the given math (inline); \bschar{} becomes an escape character, and all plain \TeX\ math is available.} +\txicmd{@minus}{\ttbraced{}}{Insert a minus sign, `$-$'.} +\txicmd{@\bschar}{}{Inside \code{@math}, insert a math backslash, $\backslash$.} +\txicmd{@geq}{\ttbraced{}}{Insert a greater-than-or-equal sign, $\geq$.} +\txicmd{@leq}{\ttbraced{}}{Insert a less-than-or-equal sign, $\leq$.} + +\subsection{Explicit font selection} + +\txicmd{@b}{\ttbraced{text}}{Set \var{text} in a bold font.} +\txicmd{@i}{\ttbraced{text}}{Set \var{text} in an italic font.} +\txicmd{@r}{\ttbraced{text}}{Set \var{text} in the regular roman font.} +\txicmd{@sansserif}{\ttbraced{text}}{Set \var{text} in a sans serif font if possible.} +\txicmd{@sc}{\ttbraced{text}}{Set \var{text} in a small caps font in printed output, and uppercase in Info. No other font command has any effect in Info.} +\txicmd{@slanted}{\ttbraced{text}}{Set \var{text} in a slanted (oblique) font if possible.} +\txicmd{@t}{\ttbraced{text}}{Set \var{text} in a fixed-width, typewriter-like font.} + + +\section{Block environments} + +`Environments' in Texinfo begin with \code{@\var{envname}} on a line of +its own and continue through the following lines of input until the +corresponding \code{@end \var{envname}} is seen. + +\txicmd{@cartouche}{}{Highlight a block of text by drawing a box with rounded corners around it. Pair with \code{@end cartouche}. No effect in Info.} +\txicmd{@exdent}{line-of-text}{Output \var{line-of-text} without any indentation.} +\txicmd{@indent}{}{Insert normal paragraph indentation.} +\txicmd{@noindent}{}{Omit the normal indentation when starting a new paragraph; often used after environments.} + +\subsection{Normally-filled displays using regular text fonts} + +In these environments, the input is automatically rebroken into lines of +output as usual. + +\txicmd{@quotation}{}{Fill text, indent on both left and right, retain +normal text font. Often used for quoting text. Pair with \code{@end quotation}.} +\txicmd{@smallquotation}{}{Like \code{@quotation}, but select a smaller (text) font where possible. Pair with \code{@end quotation}.} +\txicmd{@indentedblock}{}{Fill text, indent on left (but not right), retain normal text font. Pair with \code{@end indentedblock}.} +\txicmd{@smallindentedblock}{}{Like \code{@indentedblock}, but select a smaller (text) font where possible. Pair with \code{@end smallindentedblock}.} +\txicmd{@raggedright}{}{Leave right end ragged, but otherwise fill text; retain normal text font. Pair with \code{@end raggedright}.} + +\subsection{Line-for-line displays using regular text fonts} + +In these environments, each line of input is a line of output. + +\txicmd{@display}{}{Begin displayed text: do not fill, but indent text on left; retain normal text font. Pair with \code{@end display}.} +\txicmd{@smalldisplay}{}{Like \code{@display}, but select a smaller (text) font where possible. Pair with \code{@end smalldisplay}.} +\txicmd{@format}{}{Begin formatted text: do not fill, retain normal margins and normal text font. Pair with \code{@end format}.} +\txicmd{@smallformat}{}{Like \code{@format}, but select a smaller (text) font where possible. Pair with \code{@end smallformat}.} +\txicmd{@flushleft}{}{Left justify lines, leaving the right end ragged: do not fill text, retain normal margins and normal text font. Pair with \code{@end flushleft}.} +\txicmd{@flushright}{}{Right justify lines, leaving the left end ragged: do not fill text, retain normal margins and normal text font. Pair with \code{@end flushright}.} + +\subsection{Displays using fixed-width fonts} + +In these environments also, each line of input is a line of output. + +\txicmd{@example}{}{Begin an example. Indent text, do not fill, and select fixed-width font. Pair with \code{@end example}.} +\txicmd{@smallexample}{}{Like \code{@example}, but where possible, print text in a smaller font. Pair with \code{@end smallexample}.} +\txicmd{@lisp}{}{Like \code{@example}, but specifically for an example of Lisp code. Pair with \code{@end lisp}.} +\txicmd{@smalllisp}{}{Begin an example specifically of Lisp code; same effects as \code{@smallexample}. Pair with \code{@end smalllisp}.} +\txicmd{@verbatim}{}{Output the text of the environment exactly as is, without indentation. Pair with \code{@end verbatim}.} + + +\section{Lists and tables} + +\txicmd{@itemize}{mark-command}{Begin an unordered list, using \code{@item} for each entry, which consist of indented paragraphs, with a mark such as \code{@bullet} inside the left margin at the beginning of each item. Pair with \code{@end itemize}.} +\txicmd{@enumerate}{\rmbrack[number-or-letter]}{Begin a numbered list, using \code{@item} for each entry. Optionally, start list with \var{number-or-letter} and count from there; by default, number consecutively from `1'. Pair with \code{@end enumerate}.} +\txicmd{@table}{formatting-command}{Begin a two-column table (description list), using \code{@item} for each entry. Write each first column entry on the same line as \code{@item}. \var{formatting-command} is applied to each first column entry. Pair with \code{@end table}.} +\txicmd{@ftable}{formatting-command}{Like \code{@table}, but automatically enter each first column entry in the function index.} +\txicmd{@vtable}{formatting-command}{Like \code{@table}, but automatically enter each first column entry in the variable index.} +\txicmd{@multitable}{column-width-spec}{Begin multi-column table; start rows with \code{@item} or \code{@headitem}. Pair with \code{@end multitable}.} +\txicmd{@tab}{}{Separate columns in a row of a multitable.} +\txicmd{@item}{}{Begin an item for the list and table commands.} +\txicmd{@itemx}{}{Used only with \code{@table}. Like \code{@item} but do not generate extra preceding vertical space. When several items have the same description, use \code{@item} for the first and \code{@itemx} for the rest.} +\txicmd{@headitem}{}{Used only for multitables. Like \code{@item}, but indicates a heading row.} +\txicmd{@headitemfont}{\ttbraced{text}}{Set \var{text} in the heading row font.} +\txicmd{@asis}{text}{Prints \var{text} as-is; used as \var{formatting-command} for tables when no highlighting is desired.} + + +\section{Floating displays} + +\txicmd{@float}{}{Environment enclosing material which can float. Pair with \code{@end float}.} +\txicmd{@listoffloats}{}{Generate a list of floats for a given float type.} +\txicmd{@caption}{}{Define the full caption for a \code{@float} anywhere in the float environment.} +\txicmd{@shortcaption}{}{Define the short caption for a \code{@float}, used in the list of floats.} +\txicmd{@image}{\ttbraced{filename, \rmbrack[width], \rmbrack[height], \rmbrack[alt], \rmbrack[ext]}}{Include graphics image in external \var{filename} scaled to the given width and/or height, using alt text and looking for \samp{\var{filename}.\var{ext}} first. Can occur inline or by itself on the page.} + +\subsection{Footnotes} +\txicmd{@footnote}{\ttbraced{text-of-footnote}}{Insert a footnote: \var{text-of-footnote} is printed at the bottom of the page by \TeX, while Info and others may format at either (by default) the end of the current node, or in a separate node.} +\txicmd{@footnotestyle}{style}{Specify footnote style: \samp{end} or \samp{separate}.} + + +\section{Indices} + +\txicmd{@cindex}{entry}{Add entry to the index of concepts.} +\txicmd{@findex}{entry}{Add entry to the index of functions.} +\txicmd{@kindex}{entry}{Add entry to the index of keys.} +\txicmd{@pindex}{entry}{Add entry to the index of programs.} +\txicmd{@tindex}{entry}{Add entry to the index of data types.} +\txicmd{@vindex}{entry}{Add entry to the index of variables.} +\txicmd{@defindex}{newidx}{Define a new index and its indexing command. Format entries as regular text.} +\txicmd{@defcodeindex}{newidx}{Define a new index and its indexing command (namely, \code{@\var{newidx}index}). Format entries in this index with \code{@code}.} +\txicmd{@syncodeindex}{from-index to-index}{Merge the contents of \var{from-index} into \code{to-index}, formatting the entries in \var{from-index} with \code{@code}.} +\txicmd{@synindex}{from-index to-index}{Merge the contents of \var{from-index} into \var{to-index}; no special formatting.} +\txicmd{@printindex}{index-name}{Generate an alphabetized index (using two columns in a printed manual).} +\txicmd{@sortas}{\ttbraced{key}}{Specify a string by which to sort an +index entry.} + + +\section{Insertions within a paragraph} + +\subsection{Characters special to Texinfo} + +\txicmd{@@}{, \code{@atchar\ttbraced{}}}{Insert an at sign, `@'.} +\txicmd{@\lbracechar}{, \code{@lbracechar\ttbraced{}}}{Insert a left brace, `$\{$'.} +\txicmd{@\rbracechar}{, \code{@rbracechar\ttbraced{}}}{Insert a right brace, `$\}$'.} +\txicmd{@backslashchar}{\ttbraced{}}{Insert a typewriter backslash, {\tt\char`\\}.} +\txicmd{@\&}{, \code{@ampchar\ttbraced{}}}{Insert an ampersand, `\&'.} +\txicmd{@comma}{\ttbraced{}}{Insert a comma character; needed only when a literal comma would be an argument separator, as in \code{@xref}.} +\txicmd{@hashchar}{\ttbraced{}}{Insert a hash character, \#; needed only when a literal hash would introduce a \code{\#line} directive.} +\txicmd{@\var{whitespace}}{}{An \code{@} followed by a space, tab, or newline produces a normal, stretchable, interword space.} + +\subsection{Spacing refinements} + +\txicmd{@:}{}{Tell \TeX\ to refrain from inserting extra whitespace after an immediately preceding period, question mark, exclamation mark, or colon, as \TeX\ normally would.} +\txicmd{@.}{}{Insert a period that ends a sentence; typically needed after an end-of-sentence capital letter.} +\txicmd{@?}{}{Insert a question mark that ends a sentence.} +\txicmd{@!}{}{Insert an exclamation point that ends a sentence.} +\txicmd{@dmn}{\ttbraced{dimension}}{Format a unit of measure, as in `12\thinspace{}pt'. Causes \TeX\ to insert a thin space before \var{dimension}. No effect in Info.} + +\subsection{Accents} + +Braces are optional for the arguments to the accent commands, with the +exception of \code{@tieaccent}. + +\txicmd{@"}{c}{Generate an umlaut, \"o.} +\txicmd{@'}{c}{Generate an acute accent, \'o.} +\txicmd{@,}{c}{Generate a cedilla accent, \c c.} +\txicmd{@=}{c}{Generate a macron accent, \=o.} +\txicmd{@^}{c}{Generate a circumflex (hat) accent, \^o.} +\txicmd{@`}{c}{Generate a grave accent, \'o.} +\txicmd{@\tildechar}{c}{Generate a tilde accent, \~o.} +\txicmd{@dotaccent}{c}{Generate a dot (over) accent, \.o.} +\txicmd{@H}{c}{Generate a long Hungarian umlaut accent, \H o.} +\txicmd{@ogonek}{c}{Generate an ogonek diacritic, \ogonek{a}.} +\txicmd{@ringaccent}{c}{Generate a ring accent, \accent23o.} +\txicmd{@tieaccent}{\ttbraced{cc}}{Generate a tie-after accent, \t{oo}; argument must be given in braces.} +\txicmd{@u}{c}{Generate a breve accent, \u{o}.} +\txicmd{@ubaraccent}{c}{Generate an underbar accent, \b{o}.} +\txicmd{@udotaccent}{c}{Generate an underdot accent, \d{o}.} +\txicmd{@v}{c}{Generate a check (hacek) accent, \v{o}.} + +\subsection{Non-English characters} + +\txicmd{@AA\txicmdarg{\ttbraced{}}, @aa}{\ttbraced{}}{Generate uppercase \AA\ and lowercase \aa.} +\txicmd{@AE\txicmdarg{\ttbraced{}}, @ae}{\ttbraced{}}{Generate uppercase \AE\ and lowercase \ae.} +\txicmd{@DH\txicmdarg{\ttbraced{}}, @dh}{\ttbraced{}}{Generate uppercase \DH\ and lowercase \dh.} +\txicmd{@L\txicmdarg{\ttbraced{}}, @l}{\ttbraced{}}{Generate uppercase \L\ and lowercase \l.} +\txicmd{@O\txicmdarg{\ttbraced{}}, @o}{\ttbraced{}}{Generate uppercase \O\ and lowercase \o.} +\txicmd{@OE\txicmdarg{\ttbraced{}}, @oe}{\ttbraced{}}{Generate uppercase \OE\ and lowercase \oe.} +\txicmd{@TH\txicmdarg{\ttbraced{}}, @th}{\ttbraced{}}{Generate uppercase \TH\ and lowercase \th.} +\txicmd{@dotless}{\ttbraced{\code{i|j}}}{Generate dotless \i\ and \j.} +\txicmd{@exclamdown}{\ttbraced{}}{Generate an upside-down exclamation point, \raise.4ex\hbox{<}.} +\txicmd{@ordf\txicmdarg{\ttbraced{}}, @ordm}{\ttbraced{}}{Generate \ordf\ and lowercase \ordm.} +\txicmd{@questiondown}{\ttbraced{}}{Generate an upside-down question mark, \raise.4ex\hbox{?`}.} +\txicmd{@ss}{\ttbraced{}}{Generate the German sharp-S (es-zet) letter, \ss.} + +\subsection{Other text characters and logos} + +\txicmd{@LaTeX}{\ttbraced{}}{Insert the \LaTeX\ logo.} +\txicmd{@TeX}{\ttbraced{}}{Insert the \TeX\ logo.} +\txicmd{@bullet}{\ttbraced{}}{Insert a large round dot, $\bullet$ (\samp{*} in Info).} +\txicmd{@copyright}{\ttbraced{}}{Insert the copyright symbol, \copyright.} +\txicmd{@dots}{\ttbraced{}}{Insert an ellipsis, `\dots'.} +\txicmd{@enddots}{\ttbraced{}}{Insert an end-of-sentence ellipsis, `\dots' (more following space in \TeX.)} +\txicmd{@euro}{\ttbraced{}}{Insert the Euro currency sign, \euro.} +\txicmd{@guillemetleft\ttbraced{} @guillemetright\ttbraced{} @guillemotleft\ttbraced{} @guillemotright @guilsinglleft\ttbraced{} @guilsinglright\ttbraced{} @quotedblbase\ttbraced{} @quotedblleft @quotedblright\ttbraced{} @quoteleft\ttbraced{} @quoteright\ttbraced{} @quotesinglbase\ttbraced{}}{}{Insert various quotation marks: \guillemetleft\ \guillemetright\ \guillemotleft\ \guillemotright\ \guilsinglleft\ \guilsinglright\ \quotedblbase\ \quotedblleft\ \quotedblright\ \quoteleft\ \quoteright\ \quotesinglbase.} +\txicmd{@pounds}{\ttbraced{}}{Insert the pounds sterling currency sign, {\it\$}.} +\txicmd{@registeredsymbol}{\ttbraced{}}{Insert the registered symbol, \registeredsymbol.} +\txicmd{@textdegree}{\ttbraced{}}{Insert the degree symbol, \raise.8ex\hbox{$\circ$}.} +\txicmd{@today}{\ttbraced{}}{Insert the current date, in `1 Jan 2000' style.} +\txicmd{@U}{\ttbraced{x}}{Insert Unicode character U+\var{x} (hex).} + +\subsection{Glyphs for code examples} + +\txicmd{@equiv}{\ttbraced{}}{Indicate equivalence of two forms, $\equiv$.} +\txicmd{@error}{\ttbraced{}}{Indicate an error message, \error.} +\txicmd{@expansion}{\ttbraced{}}{Indicate the result of a macro expansion, \expansion.} +\txicmd{@point}{\ttbraced{}}{Indicate the position of point in a buffer, \point.} +\txicmd{@print}{\ttbraced{}}{Indicate printed output, \print.} +\txicmd{@result}{\ttbraced{}}{Indicate the result of an expression, \result.} + + +\section{Making and preventing breaks} + +\txicmd{@*}{}{Force a line break.} +\txicmd{@/}{}{Generates no output, but allows a line break.} +\txicmd{@-}{}{Insert a discretionary hyphenation point.} +\txicmd{@hyphenation}{\ttbraced{hy-phen-a-ted words}}{Explicitly define hyphenation points.} +\txicmd{@tie}{\ttbraced{}}{Generate a normal interword space at which a line break is not allowed.} +\txicmd{@w}{\ttbraced{text}}{Disallow line breaks within \var{text}.} +\txicmd{@refill}{}{Does nothing (previously refilled and indented the preceding paragraph for Info).} + +\subsection{Vertical space} + +\txicmd{@group}{\dots\code{@end group}}{In \TeX\ output, disallow page breaks in enclosed text; ignored otherwise.} +\txicmd{@need}{mils}{Start a new page in a printed manual if fewer than \var{mils} thousandths of an inch remain on the current page. Ignored in other formats.} +\txicmd{@page}{}{Start a new page in a printed manual. Ignored in other formats.} +\txicmd{@sp}{n}{Skip \var{n} blank lines.} +\txicmd{@vskip}{amount}{In a printed manual, insert whitespace \var{amount}. Ignored in other formats.} + + +\section{Definition commands} + +The \code{...x} variant of each command is analogous to \code{@itemx}, +leaving no extra space above. All definition commands must be written +entirely on one line. Multiword arguments must be enclosed in braces. +Descriptive text follows, ended by \samp{@end \var{defcmdname}}. + +\subsection{Function-like definitions, untyped} + +\txicmdx{@deffn}{category name arguments}{Format a description for a function, interactive command, or similar entity that may take arguments. Its arguments are the \var{category} of entity being described, the \var{name} of this particular entity, and the entity's \var{arguments}, if any.} +\txicmdx{@defun}{name arguments}{Format a description for a function; equivalent to \samp{@deffn Function \dots}.} +\txicmdx{@defmac}{name arguments}{Format a description for a macro; equivalent to \samp{@deffn Macro \dots}.} +\txicmdx{@defspec}{name arguments}{Format a description for a special form; equivalent to \samp{@deffn \ttbraced{Special Form} \dots}.} + +\subsection{Function-like definitions, typed} + +\txicmdx{@deftypefn}{category data-type name arguments}{Like \code{@deffn}, but for typed entities.} +\txicmdx{@deftypefun}{data-type name arguments}{Like \code{@defun}, but for typed entities; equivalent to \samp{@deftypefn Function \dots}.} + +\subsection{Variable-like definitions, untyped} + +\txicmdx{@defvr}{category name}{Format a description for any kind of variable. Its arguments are the \var{category} of the entity and the \var{name} of this particular entity.} +\txicmdx{@defvar}{name}{Format a description for a variable; equivalent to \samp{@defvr Variable \dots}.} +\txicmdx{@defopt}{name}{Format a description for a user option; equivalent to \samp{@defvar \ttbraced{User Option} \dots}.} + +\subsection{Variable-like definitions, typed} + +\txicmdx{@deftypevr}{category data-type name}{Like \code{@defvr}, but for typed entities.} +\txicmdx{@deftypevar}{data-type name}{Like \code{@defvar}, but for typed entities; equivalent to \samp{@deftypevr Variable \dots}.} + +\subsection{Type definitions} + +\txicmdx{@deftp}{category name attributes}{Format a description for a data type. Its arguments are the \var{category}, the \var{name} of the type (e.g., \samp{int}), and then the \var{attributes} of objects of that type.} + +\subsection{Object-oriented entities, untyped} + +\txicmdx{@defcv}{category class name}{Format a description for a variable associated with a class in object-oriented programming.} +\txicmdx{@defivar}{class name}{Format a description for an instance variable \var{name} in object-oriented programming; equivalent to \samp{@defcv \ttbraced{Instance Variable of} \dots}.} +\txicmdx{@defmethod}{class name arguments}{Format a description for method \var{name}; equivalent to \samp{@defop \ttbraced{Method on} \dots}.} +\txicmdx{@defop}{category class name arguments}{Format a description for an operation in object-oriented programming. Its arguments are the \var{category} of the variable, the \var{class} to which it belongs, its \var{name}, and any \var{arguments}.} + +\subsection{Object-oriented entities, typed} + +\txicmdx{@deftypecv}{category class datatype name}{Like \code{@defcv}, but for typed class variables.} +\txicmdx{@deftypeivar}{class data-type name}{Like \code{@defivar}, but for typed instance variables.} +\txicmdx{@deftypemethod}{class data-type name arguments}{Format a description for a typed method in object-oriented programming; equivalent to \samp{@deftypeop \ttbraced{Method on} \dots}.} +\txicmdx{@deftypeop}{category class data-type name arguments}{Format a description for a typed operation in object-oriented programming.} + + +\section{Conditionally (in)visible text} + +\txicmd{@comment}{comment}{Begin a comment in Texinfo. The rest of the line is not visible in any output.} +\txicmd{@c}{comment}{Synonym for \code{@comment}. \code{DEL} also starts a comment.} +\txicmd{@ignore}{\dots\code{@end ignore}}{Text that will not appear in any output.} + +\subsection{Output formats} + +\txicmd{@ifdocbook}{\dots\code{@end ifdocbook}}{Texinfo text to appear only in Docbook output.} +\txicmd{@ifhtml}{\dots\code{@end ifhtml}}{Text to appear only in \acro{HTML} output.} +\txicmd{@ifinfo}{\dots\code{@end ifinfo}}{Text to appear in both Info and (for historical compatibility) plain text output.} +\txicmd{@ifplaintext}{\dots\code{@end ifplaintext}}{Text to appear only in plain text output.} +\txicmd{@iftex}{\dots\code{@end iftex}}{Text to appear only in the \TeX\ output.} +\txicmd{@ifxml}{\dots\code{@end ifxml}}{Text to appear only in \acro{XML} output.} +\txicmd{@ifnotdocbook @ifnothtml @ifnotplaintext @ifnottex @ifnotxml}{\dots\code{@end ifnot\var{format}}}{Begin text to be ignored in one output format but no others: \code{@ifnothtml} text is omitted from \acro{HTML} output, etc.} +\txicmd{@ifnotinfo}{\dots\code{@end ifnotinfo}}{Like the other \code{@ifnot\dots} commands, but omit from plain text output as well as Info.} +\txicmd{@inlinefmt}{\ttbraced{format, text}}{Include Texinfo \var{text} only in \var{format} output.} +\txicmd{@inlinefmtifelse}{\ttbraced{format, then-text, else-text}}{Include either \var{then-text} or \var{else-text} according to whether \var{format} is output.} + +\subsection{Raw formatter text} + +\txicmd{@docbook}{\dots\code{@end docbook}}{Enter Docbook completely.} +\txicmd{@html}{\dots\code{@end html}}{Enter \acro{HTML} completely.} +\txicmd{@tex}{\dots\code{@end tex}}{Enter \TeX\ completely (e.g., \bschar\ becomes an escape character).} +\txicmd{@xml}{\dots\code{@end xml}}{Enter \acro{XML} completely.} +\txicmd{@inlineraw}{\ttbraced{format, text}}{Include raw \var{text} only in \var{format} output.} + +\subsection{Document variables} + +\txicmd{@set}{name \rmbrack[string]}{Define the Texinfo variable \var{name}, optionally to the value \var{string}.} +\txicmd{@clear}{name}{Undefine \var{name}.} +\txicmd{@value}{\ttbraced{name}}{Insert the value of \var{name}.} +\txicmd{@ifset}{name \dots\code{@end ifset}}{If \var{name} is set, format enclosed text.} +\txicmd{@ifclear}{name \dots\code{@end ifclear}}{If \var{name} is not set, format enclosed text.} +\txicmd{@inlineifset}{\ttbraced{name, text}}{If \var{name} is set, format \var{text}.} +\txicmd{@inlineifclear}{\ttbraced{name, text}}{If \var{name} is not set, format \var{text}.} + +\subsection{Testing for commands} + +\txicmd{@ifcommanddefined}{\var{cmd} \dots\code{@end ifcommanddefined}}{\linebreak Text to appear only if \code{@}\var{cmd} is defined \dots} +\txicmd{@ifcommandnotdefined}{\var{cmd} \dots\code{@end ifcommandnotdefined}}{\linebreak\dots\ or not defined.} +\txicmd{txicommandconditionals}{}{Texinfo variable predefined to true.} + + +\section{Defining new Texinfo commands} + +\txicmd{@alias}{new\code{=}existing}{Make the command \code{@new} a synonym for the existing command \code{@existing}.} +\txicmd{@macro}{macroname \ttbraced{\var{params}} \dots\code{@end macro}}{Define a new Texinfo command \code{@\var{macroname}}.} +\txicmd{@unmacro}{macroname}{Undefine \code{@\var{macroname}} if it is defined.} +\txicmd{@definfoenclose}{newcmd\code{,} before\code{,} after}{Can only be used within \code{@ifinfo}; create a new command that encloses its argument in the \var{before} and \var{after} strings.} + + +\section{File inclusion} + +\txicmd{@include}{filename}{Read the contents of Texinfo source file \var{filename}.} +\txicmd{@verbatiminclude}{filename}{Incorporate the contents of \var{filename} in the output, exactly as is (in the fixed-width font).} + + +\section{Formatting and headers/footers for \TeX} + +\txicmd{@allowcodebreaks}{\code{true|false}}{Control breaks at \code{-} and \code{_} in \TeX; default true.} +\txicmd{@finalout}{}{Omit large black rectangles at overfull lines in \TeX\ output.} +\txicmd{@fonttextsize}{\code{10|11}}{Change size of main body font in \TeX.} + +\subsection{Paper sizes} + +The default paper size is \acro{US} letter-size, 8x11in. + +\txicmd{@smallbook}{}{Format for a 7x9.25in trim size.} +\txicmd{@afourpaper, @afivepaper}{}{Format for A4 and A5 paper sizes.} +\txicmd{@afourlatex}{}{Variant for A4 with more whitespace.} +\txicmd{@afourwide}{}{Format for A4 in landscape.} +\txicmd{@pagesizes}{\rmbrack[{width{\small][}, height}]}{Format for the explicitly given page dimensions, \var{width} by \var{height}.} + +\subsection{Page headers and footers} + +\def\footingheading#1#2{% #1=odd/even/every, #2=description +\txicmd{@#1footing}{\rmbrack[left] \code{@|} \rmbrack[center] \code{@|} \rmbrack[right]}{} +\vskip-.3\parskip +\txicmd{@#1heading}{\rmbrack[left] \code{@|} \rmbrack[center] \code{@|} \rmbrack[right]}{\hfill Specify page footings resp.\ headings for #2.} +\vskip+.1\parskip +} + +\footingheading{odd}{odd-numbered (right-hand) pages} +\footingheading{even}{even-numbered (left-hand) pages} +\footingheading{every}{every page} + +\txicmd{@thischapter, @thischaptername, @thischapternum, @thisfile, @thispage, @thistitle}{}{These commands are only allowed in a heading or footing. They stand for, respectively, the number and name of the current chapter (in the format `Chapter~1: Title'), the current chapter name only (`Title'), the current chapter number only (`1'), the filename, the current page number, and the title of the document.} + + +\section{Document preferences} + +It is usually best to omit any of these (merely preferential) settings +from the Texinfo document, so users can easily override the defaults +when processing the document. + +\txicmd{@codequoteundirected}{\code{on|off}}{Use undirected single quote for \code{'}; default off.} +\txicmd{@codequotebacktick}{\code{on|off}}{Use backtick (standalone grave accent) for \code{`}; default off.} +\txicmd{@deftypefnnewline}{\code{on|off}}{Put return type on a line by itself; default off.} +\txicmd{@exampleindent}{indent}{Indent example-like environments by \var{indent} number of spaces (perhaps 0).} +\txicmd{@firstparagraphindent}{\code{insert|none}}{Indent first paragraphs after section headings, or not.} +\txicmd{@headings}{\code{on|off|single|double}}{Turn page headings on or off, specify single-sided or double-sided page headings for printing.} +\txicmd{@kbdinputstyle}{\code{code|distinct|example}}{Specify font for \code{@kbd}: normal \code{@code} font, a distinct (slanted) typewriter font, or a distinct font only within \code{@example} and similar.} +\txicmd{@paragraphindent}{indent}{Indent paragraphs by \var{indent} number of spaces (perhaps 0); preserve source file indentation if \var{indent} is the string \code{asis}.} +\txicmd{@setchapternewpage}{\code{on|off|odd}}{Specify whether chapters start on new pages, and if so, whether on odd-numbered (right-hand) new pages; also set page headings accordingly.} +\txicmd{@urefbreakstyle}{\code{after|before|none}}{Specify how \code{@uref} should break at special characters; default \code{after}.} + + +\section{Ending a Texinfo document} + +\txicmd{@bye}{}{End reading the Texinfo source. Any following text in the file is ignored.} + +\smallskip Finally, this meta-command doesn't fit anywhere else: +\txicmd{@errormsg}{\ttbraced{msg}}{Report \var{msg} as an error.} + + + +\chapter{Reading Info files} + +There are two main Info readers: \code{M-x info} (\code{C-h i}) in GNU +Emacs, and the standalone \code{info} program. These basic keystrokes +work in both. + +\begininfokeys % +\infokey q Quit Info altogether.\cr +\infokey h Invoke the Info tutorial.\cr + +\infokey Up Move up one line.\cr +\infokey Down Move down one line.\cr +\infokey DEL Scroll backward one screenful.\cr +\infokey SPC Scroll forward one screenful.\cr +\infokey Home,b Go to the beginning of this node.\cr +\infokey End Go to the end of this node.\cr + +\infokey TAB Skip to the next hypertext link.\cr +\infokey RET Follow the hypertext link under the cursor.\cr +\infokey l Go back to the last node seen in this window.\cr + +\infokey [ Go to the previous node in the document.\cr +\infokey ] Go to the next node in the document.\cr +\infokey p Go to the previous node on this level.\cr +\infokey n Go to the next node on this level.\cr +\infokey u Go up one level.\cr +\infokey t Go to the top node of this document.\cr +\infokey d Go to the main `directory' node.\cr + +\infokey 1...9 Pick the first...ninth item in this node's menu.\cr +\infokey 0 Pick the last item in this node's menu.\cr +\infokey m Pick a menu item specified by name.\cr +\infokey f Follow a cross reference specified by name.\cr +\infokey g Go to a node specified by name.\cr + +\infokey s Search forward for a specified string.\cr +\infokey \lbracechar{} Search for previous occurrence.\cr +\infokey \rbracechar{} Search for next occurrence.\cr +\infokey i Search for a specified string in the index, and\cr +\infokey {} select the node referenced by the first entry found.\cr +\infokey I Synthesize menu of matching index entries.\cr + +\infokey C-g Cancel the current operation.\cr +\endinfokeys + +The Texinfo manual is available via \code{info texinfo}\linebreak +(and at \code{http://www.gnu.org/software/texinfo/manual}). + +\copyrightnotice +\bye + +For make ccheck - Commands we deliberately haven't documented: +\txicmd{@validatemenus}{}{} diff --git a/macros/texinfo/texinfo/doc/short-sample-ja.texi b/macros/texinfo/texinfo/doc/short-sample-ja.texi new file mode 100644 index 0000000000..560e40da8d --- /dev/null +++ b/macros/texinfo/texinfo/doc/short-sample-ja.texi @@ -0,0 +1,64 @@ +\input texinfo-ja + +@documentencoding UTF-8 +@documentlanguage ja + +@settitle サンプル マニュアル 1.0 日本語版 + +@copying +これは完全な Texinfo ファイルの短い例です。 + +Copyright @copyright{} 2016 Free Software Foundation, Inc. +@end copying + +@titlepage +@title サンプル タイトル +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@c 最初に目次を出力します。 +@contents + +@ifnottex +@node Top +@top GNU サンプル + +このマニュアルは GNU サンプル +(version @value{VERSION}, @value{UPDATED}) +用です。 +@end ifnottex + +@menu +* 第一章:: 第一章は + このサンプルの唯一の章です +* 索引:: 完全な索引 +@end menu + + +@node 第一章 +@chapter 第一章 + +@cindex 章, 第一 + +これは第一章です。 +@cindex 索引項目, 他 + +ここは番号付き一覧です。 + +@enumerate +@item +これは最初の項目です。 + +@item +これは二番目の項目です。 +@end enumerate + + +@node 索引 +@unnumbered 索引 + +@printindex cp + +@bye diff --git a/macros/texinfo/texinfo/doc/stamp-1 b/macros/texinfo/texinfo/doc/stamp-1 new file mode 100644 index 0000000000..bd8d35fb8b --- /dev/null +++ b/macros/texinfo/texinfo/doc/stamp-1 @@ -0,0 +1,4 @@ +@set UPDATED 16 February 2019 +@set UPDATED-MONTH February 2019 +@set EDITION 6.6 +@set VERSION 6.6 diff --git a/macros/texinfo/texinfo/doc/stamp-vti b/macros/texinfo/texinfo/doc/stamp-vti new file mode 100644 index 0000000000..bd8d35fb8b --- /dev/null +++ b/macros/texinfo/texinfo/doc/stamp-vti @@ -0,0 +1,4 @@ +@set UPDATED 16 February 2019 +@set UPDATED-MONTH February 2019 +@set EDITION 6.6 +@set VERSION 6.6 diff --git a/macros/texinfo/texinfo/doc/texinfo-ja.tex b/macros/texinfo/texinfo/doc/texinfo-ja.tex new file mode 100644 index 0000000000..6434758955 --- /dev/null +++ b/macros/texinfo/texinfo/doc/texinfo-ja.tex @@ -0,0 +1,84 @@ +% texinfo-ja.tex -- Japanese texinfo.tex loader +% Some CJK packages are necessary to load before texinfo.tex. +% +% Copyright 2016, 2017 Free Software Foundation, Inc. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the license, or (at +% your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +% Written by Masamichi Hosoda, 6 May 2016, <trueroad@trueroad.jp> + +% +% For LuaTeX +% +\ifx\luatexversion\thisisundefined +\else + % LuaTeX 0.95+ is required. + \ifnum\luatexversion<95 + \errmessage{LuaTeX 0.95+ is required} + \fi + % LuaTeX-ja: Typeset Japanese with Lua(La)TeX + % http://www.ctan.org/tex-archive/macros/luatex/generic/luatexja + \openin 1 luatexja.sty \ifeof 1 + \errmessage{LuaTeX-ja is not found. + It is required for Japanese Texinfo files with LuaTeX. + http://www.ctan.org/tex-archive/macros/luatex/generic/luatexja + It might be contained in texlive-lang-japanese package} + \else + \input luatexja.sty + \def\txijapackage{LaTeX-ja} + \fi +\fi + +% +% For XeTeX +% +\ifx\XeTeXrevision\thisisundefined +\else + % XeTeX 0.9998+ is required. + \ifnum\strcmp{\the\XeTeXversion\XeTeXrevision}{0.9998}<0 + \errmessage{XeTeX 0.9998+ is required} + \fi + % zhspacing: Spacing for mixed CJK-English documents in XeTeX + % http://www.ctan.org/tex-archive/macros/xetex/generic/zhspacing + % + % This package is originally for Chinese, + % but can also used in Japanese. + % + \openin 1 zhspacing.sty \ifeof 1 + \errmessage{zhspacing is not found. + It is required for Japanese Texinfo files with XeTeX. + http://www.ctan.org/tex-archive/macros/xetex/generic/zhspacing + It might be contained in texlive-lang-chinese. + (This package is for Chinese, but can also used in Japanese)} + \else + \def\zhfont{dummy} % Cancel the request of SimSun font + \def\zhpunctfont{dummy} % Cancel the request of SimSun font + \input zhspacing.sty + \zhspacing + \def\txijapackage{zhspacing} + \fi +\fi + +% +% For others +% +\ifx\luatexversion\thisisundefined + \ifx\XeTeXrevision\thisisundefined + \errmessage{The TeX engine is not LuaTeX / XeTeX. + LuaTeX / XeTeX is required for Japanese Texinfo files} + \fi +\fi + +% Original texinfo.tex +\input texinfo.tex diff --git a/macros/texinfo/texinfo/doc/texinfo-tex-test.WIDOWs b/macros/texinfo/texinfo/doc/texinfo-tex-test.WIDOWs new file mode 100644 index 0000000000..834c9036d8 --- /dev/null +++ b/macros/texinfo/texinfo/doc/texinfo-tex-test.WIDOWs @@ -0,0 +1,112 @@ +\initial {K} +\entry {\code {kbd}}{63} +\entry {\code {kbdinputstyle}}{63} +\entry {\code {key}}{64} +\entry {\code {kindex}}{97} +\initial {L} +\entry {\code {l}}{109} +\entry {\code {L}}{109} +\entry {\code {LaTeX}}{112} +\entry {\code {lbracechar\lbracechar \rbracechar \r {(literal \samp {\lbracechar })}}}{103} +\entry {\code {leq}}{114} +\entry {\code {{\tt \backslashcurfont }linkcolor}}{59} +\entry {\code {lisp}}{76} +\entry {\code {listoffloats}}{91} +\entry {\code {lowersections}}{47} +\initial {M} +\entry {\code {macro}}{149} +\entry {\code {{\tt \backslashcurfont }mag \r {(raw \TeX {} magnification)}}}{173} +\entry {\code {majorheading}}{44} +\entry {\code {makeinfo-buffer}}{199} +\entry {\code {makeinfo-kill-job}}{200} +\entry {\code {makeinfo-recenter-output-buffer}}{200} +\entry {\code {makeinfo-region}}{199} +\entry {\code {math}}{111} +\entry {\code {{\tt \backslashcurfont }mathopsup}}{111} +\entry {\code {menu}}{38} +\entry {\code {minus}}{114} +\entry {\code {move_index_entries_after_items}}{195} +\entry {\code {multitable}}{87} +\initial {N} +\entry {\code {need}}{122} +\entry {\code {<newline>}}{105} +\entry {\code {next-error}}{199} +\entry {\code {node}}{32} +\entry {\code {noindent}}{78} +\entry {\code {novalidate}}{165} +\initial {O} +\entry {\code {o}}{109} +\entry {\code {O}}{109} +\entry {\code {occur}}{277} +\entry {\code {occur-mode-goto-occurrence}}{259} +\entry {\code {oddfooting}}{270} +\entry {\code {oddfootingmarks}}{272} +\entry {\code {oddheading}}{270} +\entry {\code {oddheadingmarks}}{272} +\entry {\code {oe}}{109} +\entry {\code {OE}}{109} +\entry {\code {ogonek}}{108} +\entry {\code {option}}{67} +\entry {\code {ordf}}{109} +\entry {\code {ordm}}{109} +\initial {P} +\entry {\code {page}}{121} +\entry {\code {page\r {, within \code {\@titlepage}}}}{20} +\entry {\code {pagesizes}}{172} +\entry {\code {paragraphindent}}{29} +\entry {\code {parse}}{185} +\entry {\code {part}}{46} +\entry {\code {pdf}}{185} +\entry {\code {phoo}}{155} +\entry {\code {pindex}}{97} +\entry {\code {plaintexinfo}}{185} +\entry {\code {plaintext}}{185} +\entry {\code {point}}{116} +\entry {\code {pounds}}{113} +\entry {\code {print}}{115} +\entry {\code {printindex}}{99} +\entry {\code {ps}}{185} +\entry {\code {pxref}}{55} +\initial {Q} +\entry {\code {questiondown}}{109} +\entry {\code {quotation}}{73} +\entry {\code {quotedblbase}}{110} +\entry {\code {quotedblleft}}{110} +\entry {\code {quotedblright}}{110} +\entry {\code {quoteleft}}{110} +\entry {\code {quoteright}}{110} +\entry {\code {quotesinglbase}}{110} +\initial {R} +\entry {\code {r \r {(roman font)}}}{71} +\entry {\code {raggedright}}{78} +\entry {\code {raisesections}}{47} +\entry {\code {rawtext}}{185} +\entry {\code {rbracechar\lbracechar \rbracechar \r {(literal \samp {\rbracechar })}}}{103} +\entry {\code {ref}}{55} +\entry {\code {refill}}{237} +\entry {\code {regenerate_master_menu}}{195} +\entry {\code {registeredsymbol}}{112} +\entry {\code {result}}{115} +\entry {\code {ringaccent}}{108} +\entry {\code {rmacro}}{150} +\initial {S} +\entry {\code {samp}}{65} +\entry {\code {sansserif \r {(sans serif font)}}}{71} +\entry {\code {sc \r {(small caps font)}}}{70} +\entry {\code {section}}{44} +\entry {\code {set}}{143} +\entry {\code {setchapternewpage}}{27} +\entry {\code {\@setcontentsaftertitlepage}}{244} +\entry {\code {setfilename}}{17} +\entry {\code {\@setshortcontentsaftertitlepage}}{244} +\entry {\code {settitle}}{18} +\entry {\code {shortcaption}}{91} +\entry {\code {shortcontents}}{24} +\entry {\code {shorttitlepage}}{21} +\entry {\code {simple_menu}}{195} +\entry {\code {slanted \r {(slanted font)}}}{71} +\entry {\code {smallbook}}{171} +\entry {\code {smalldisplay}}{76} +\entry {\code {smallexample}}{80} +\entry {\code {smallformat}}{77, 80} +\entry {\code {smallindentedblock}}{74} diff --git a/macros/texinfo/texinfo/doc/texinfo-tex-test.texi b/macros/texinfo/texinfo/doc/texinfo-tex-test.texi new file mode 100644 index 0000000000..ad1d3bb9dd --- /dev/null +++ b/macros/texinfo/texinfo/doc/texinfo-tex-test.texi @@ -0,0 +1,1610 @@ +% texinfo-tex-test.texi -- test file for texinfo.tex +% +% Copyright 2015, 2016 Free Software Foundation, Inc. +% +% This 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 file is distributed in the hope that it will be +% useful, but WITHOUT ANY WARRANTY; without even the implied warranty +% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +% General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +\input texinfo +@settitle Test Document for @file{texinfo.tex} + +@everyheading @thischapter @| @| @thissection{} p@thispage +@paragraphindent 0 + +@showboxdepth=1000 +@showboxbreadth=1000 + +@documentencoding UTF-8 + +@contents + +@part Part One@*Sample part page@sup{superscript} + +@chapter Fonts + +@macro headerline +@r{roman} @i{italic} @b{bold} @t{typewriter} @slanted{slant} @* +@sansserif{`sans serif'} @sc{`small caps'} {@ensuremath@clubsuit} +@hrule +@end macro + +A test of the fonts used in @file{texinfo.tex}. + +{@titlefonts @headerline} + +{@textfonts @headerline} + +{@reducedfonts @headerline} + +{@chapfonts @headerline} + +{@secfonts @headerline} + +{@subsecfonts @headerline} + +{@smallfonts @headerline} + +{@smallerfonts @headerline} + +@majorheading Test of @LaTeX{} logo + +{@rm @LaTeX{}} + +{@it @LaTeX{}} + +{@sl @LaTeX{}} + +{@bf @LaTeX{}} + +{@tt @LaTeX{}} + +@majorheading roman @b{bold}@sup{superscript} @LaTeX{} + +@majorheading roman@sup{sup} @b{now bold@sup{sup}@r{now roman@sup{superscript}}} + + +@heading roman @b{bold} @LaTeX{} + +@subheading roman @b{bold} @LaTeX{} + +roman@sub{sub} @b{bold@sub{sub}} + +@section Acronyms + +Test of @acronym{ACRONYM}'s. {ACRONYM}'s. + +@majorheading Test of @acronym{ACRONYM}'s. ACRONYM's hippopotamus + + +@chapter Glyph commands + +@ordf{} @ordm{} + + +@chapter Macros +@section Backslashes in macro arguments + +@macro Mac{x} +A\x\A +@end macro + +@macro Mactwo{x, y} +<\x\>.<\y\>@. +@end macro + +@rmacro RMac{x} +Z\x\Z +@end rmacro + +The number refers to the number of backslashes that should appear + +0 @Mac{} + +0 @Mac{a} + +0 @Mac{a}X + +1 @Mac{a\\} + +1 @Mac{a\}X + +1 @Mac{a\\}X + +2 @Mac{a\\\}X + +1 @Mac{\}X + +1 @Mac{\a}X + +1 @Mac{\\a}X + +1 @Mac{\\}X + +2 @Mac{\\\}X + +2 and 1 @Mac{\\\aaa\}X + +1 and 1 @Mac{\a\\b}X + +one backslash outside \ + +two backslashes outside \\ + +three backslashes outside \\\ + +0 @Mac a + +1 @Mac a\ + +2 @Mac a\\ + +3 @Mac a\\\ + +1 and 2 @Mac \a\\b + +in @@code:@* +1 @code{@Mac{\}}@* +1 @code{@Mac{\\}}@* +2 @code{@Mac{\\\}}@* +2 @code{@Mac{\\\\}} + +one backslash outside \ + +two backslashes outside \\ + +three backslashes outside \\\ + +Macros with two arguments: +0+0 @Mactwo{A,B} +0+0 @Mactwo{A, B} +1+0 @Mactwo{\A, B} +0+1 @Mactwo{A, \\B} +2+1 @Mactwo{\\\A, \\B} +2+2 @Mactwo{\\\A, \\\\B} + +Space between macro name and opening brace (thus: @samp{@@Mactwo @{}): + +0+0 @Mactwo {A,B} +0+0 @Mactwo {A, B} +1+0 @Mactwo {\A, B} +0+1 @Mactwo {A, \\B} +2+1 @Mactwo {\\\A, \\B} +2+2 @Mactwo {\\\A, \\\\B} + +space between backslashes: @Mac{\ \}@* +space between backslashes line arg: @Mac \ \ + +space after backslashes, two arguments:@* +@Mactwo{\ \\, \ \\}@* +@Mactwo{\\ \\, \\ \\}@* +@Mactwo{\\ a, \\ b}@* +@Mactwo{\ a, \ b}@* + +other spaces:@* +@Mactwo{h \\, i \\}@* +@Mactwo{h \\, i \\}@* +@Mactwo{h a, i b}@* + +@section Spaces in macro bodies + +Distance between the two x's should be the same + +@macro Mac +@example +x x +@end example +@end macro +@example +x x +@end example +@Mac + +@section Macro use inside macro argument + +@macro Innermac{arg} +xx \arg\ xx +@end macro + +@macro Outermac{arg} +\arg\ +@c +@end macro + +@Outermac{@Innermac{e}} +should be@* +xx e xx + +@section Closing brace following empty macro argument + +@macro Mac{x} +A@acronym{\x\}A +@end macro + +@Mac{} + +AA + +@section Trailing newlines in macro bodies + +Output should be doubled: + +1y + +z +x2 + +@macro nbsp +y + +z +x +@end macro + +1@nbsp{}2 + +Output should be doubled: + + +@example +1y + +z +x2 +@end example + +@example +1@nbsp{}2 +@end example + +@section Open or close a group in a macro + +Output should be doubled + +@macro Example +@example +@group +@end macro + +@macro endExample +@end group +@end example +@end macro + +x +@Example +groff [ -abceghijklpstvzCEGNRSUVXZ ] +@endExample +x + +x +@example +@group@comment +groff [ -abceghijklpstvzCEGNRSUVXZ ] +@end group +@end example +x + +x +@example +@group +groff [ -abceghijklpstvzCEGNRSUVXZ ] +@end group +@end example +x + +x +@example +@group@c +groff [ -abceghijklpstvzCEGNRSUVXZ ] +@end group +@end example +x + +xxxxxxxxxxxxxxxxxxxxxx + +@example +@group@c +groff [ -abceghijklpstvzCEGNRSUVXZ ] +@end group +@end example + +xxxxxxxxxxxxxxxxxxxxxxxxxxx + +xxxxxxxxxxxxxxxxxxxxxx + +@Example +groff [ -abceghijklpstvzCEGNRSUVXZ ] +@endExample + +xxxxxxxxxxxxxxxxxxxxxxxxxxx + +@section Braceless at end of line + +@macro Mac +value +@end macro + +Okay, we are here. The @Mac +on next line now. + +With spaces and newline. The @Mac +on next line now. + +With braces. The @Mac{} +on next line now. + +With space and braces. The @Mac {} +on next line now. + +With two spaces and braces. The @Mac {} +on next line now. + +With braces and two newlines. The @Mac{} + +in next paragraph now. + +With two newlines. The @Mac + +in next paragraph now. + +@section @,c in macro argument + +@macro mactwo{argfirst, argsecond} +\argfirst\+\argsecond\. +@end macro + +@set fc Fran@,cois +@mactwo{@value{fc},}@* +@mactwo{Fran@,cois,}@* +Fran@,cois+. + +@section Macro in argument to @@math + +@macro frac {a,b} +\a\ @over \b\ +@end macro + +exceeds @math{@frac{1,16}} pt + + +@section Trim whitespace from macro arguments + +@macro Mac{a} +<X\a\X> +@end macro + +@macro Mactwo{a,b} +<X\a\X\b\X> +@end macro + +No trimming for single-arg macros. + +@noindent @Mac{b} @Mac{ b} @Mac{b } @Mac{ b } + +@noindent @Mactwo{b,c} @Mactwo{ b, c} @Mactwo{b ,c } @Mactwo{ b , c } + + +@section Multi-line macro argument + +@macro Mac{text} +@cartouche +<@b{FIXME}> +@example +\text\ +@end example +\text\ +@noindent </> +@end cartouche +@end macro + +@Mac{ +Here's an extended +macro argument, with +newlines. + +And multiple paragraphs. +Like an argument to @b{@@footnote}. +} + +(The double space in the @code{@@example} and the fact the text is not +in bold is due to the way @code{\scantokens} inserts spaces after +control sequences. This could be worked around like + +@verbatim +@tex +@gdef@coolb#1#{@b}% +@end tex +@end verbatim + +@noindent and using @samp{@@coolb} instead of @samp{@@b}. This skips +the active space token before the opening brace. In theory this could +be done automatically, but this would be a lot of work in +@file{texinfo.tex} to do for all commands.) + + +@tex +\gdef \commenceindexnopage{% +\begingroup +\smallfonts \rm +\begindoublecolumns +\tolerance = 9500 +\plainfrenchspacing +\everypar = {}% +\catcode`\\=0 \catcode`\@=12 +} + +\gdef \commenceindex{% +\page +\commenceindexnopage +} + +\gdef \finishindex{% +\catcode`\@=0 \catcode`\\=13 +\enddoublecolumns +\endgroup +\hrule +} +@end tex + +@chapter Index display + +In these examples, a horizontal rule is at the end of each run of double +column material in order to show if any material extends below the +box containing it. + +@section Long index entries + +@commenceindex +\entry {\code {-c}}{18, 20, 22, 27, 28, 38, 43, 51, 54, 65, 83, 91, 105, +124, 125, 127, 129, 135, 139, 143, 145, 148, 187} +\entry {\code {-c}}{18, 20, 22, 27, 28, 38, 43, 51, 54, 65, 83, 91, 105, +124, 125, 127, 129, 135, 139, 143, 145, 148} +\entry{Testing for Texinfo Commands: \code {\@ifcommanddefined}, \code +{\@ifcommandnotdefined}}{148} +\entry {\code {--dereference-command-line-symlink-to-dir}}{78} +\entry {built-in shell commands, conflicts with}{119, 139, 144, 145, +148, 163, 191, 196, 197} +\finishindex + +@section End-column glue + +See next page. A little bit of space should appear at the bottom of the +second column, instead of flush bottoms and a conspicuous increase in +inter-baseline spacing. This test only works if the `R' initial is at +the start of a page. + +@commenceindex +\initial {P} +\entry {\code {PACKAGE}}{196} +\entry {\code {PACKAGE_AND_VERSION}}{196} +\entry {\code {PACKAGE_NAME}}{196} +\entry {\code {PACKAGE_URL}}{196} +\entry {\code {PACKAGE_VERSION}}{196} +\entry {Page breaks, awkward}{124} +\entry {Page breaks, forcing}{126} +\entry {Page delimiter in Texinfo mode}{261} +\entry {Page headings}{270} +\entry {Page numbering}{270} +\entry {Page sizes for books}{175} +\entry {Page sizes, customized}{175} +\entry {\code {page-delimiter}}{261} +\entry {Pages, starting odd}{29} +\entry {Paper size, A4}{175} +\entry {Paragraph indentation control}{31} +\entry {Paragraph, marking text within}{66} +\entry {\code {paragraphindent}}{187} +\entry {Parameters to macros}{154} +\entry {Parentheses in node name}{37} +\entry {Parsing errors}{202} +\entry {Part of file formatting and printing}{266} +\entry {Part pages}{50} +\entry {Partial documents, formatting}{168} +\entry {Parts of a cross reference}{54} +\entry {Parts of a master menu}{28} +\entry {Parts of a menu}{43} +\entry {Patches, contributing}{4} +\entry {PCL file, for printing}{170} +\entry {\code {pdf image inclusions}}{97} +\entry {PDF output}{176} +\entry {PDF output of urls}{64} +\entry {PDF output, overview}{5} +\entry {\code {pdfetex}}{167} +\entry {\code {pdftex}}{176} +\entry {\code {pdftex\r {, and images}}}{97} +\entry {\code {pdftxei2dvi}}{166} +\entry {Period in node name}{37} +\entry {Periods, inserting}{111} +\entry {Perl format strings for translation}{199} +\entry {Perl POD, converting to Texinfo}{200} +\entry {Permissions text, including}{22} +\entry {Permissions, printed}{25} +\entry {\code {pg} (program) index}{102} +\entry {Picas}{98} +\entry {Pictures, inserting}{97} +\entry {Pinard, Fran\,{c}ois}{7} +\entry {Plain \TeX {}}{146} +\entry {Plain text output with \option {--plaintext}}{183} +\entry {Plain text output, overview}{4} +\entry {\code {png image format}}{97} +\entry {POD, converting to Texinfo}{200} +\entry {\code {pod2texi}}{200} +\entry {Point, indicating in a buffer}{121} +\entry {Pointer creation with \code {makeinfo}}{40} +\entry {Pointer validation with \code {makeinfo}}{185} +\entry {Pointer validation, suppressing}{168} +\entry {Pointer validation, suppressing from command line}{182} +\entry {Points (dimension)}{98} +\entry {PostScript output, overview}{4} +\entry {Pounds symbol}{118} +\entry {\code {PRE_ABOUT}}{192} +\entry {\code {PRE_BODY_CLOSE}}{192} +\entry {Preamble, in Info format}{283} +\entry {Predefined names for indices}{105} +\entry {Preface, etc., and Docbook}{48} +\entry {\code {PREFIX}}{196} +\entry {Preparing for \TeX {}}{173} +\entry {Preserving HTML links to old nodes}{221} +\entry {Prev node of Top node}{38} +\entry {Preventing first paragraph indentation}{32} +\entry {Preventing line and page breaks}{124} +\entry {Print and format in Texinfo mode}{170} +\entry {Print, format from Emacs shell}{170} +\entry {Printed book and manual characteristics}{6} +\entry {Printed output, indicating}{120} +\entry {Printed output, through \command {texi2any}}{185} +\entry {Printed permissions}{25} +\entry {Printing a region or buffer}{266} +\entry {Printing an index}{104} +\entry {Printing cost, reducing}{75} +\entry {Printing cropmarks}{176} +\entry {Printing DVI files, on MS-DOS/MS-Windows}{170} +\entry {Printing hardcopy}{166} +\entry {Problems, catching}{275} +\entry {\code {PROGRAM}}{196} +\entry {Program names, indicating}{72} +\entry {\code {PROGRAM_NAME_IN_FOOTER}}{192} +\entry {Programming, glyhs for}{119} +\entry {Pronunciation of Texinfo}{3} +\entry {Prototype row, column widths defined by}{93} +\entry {Ragged left, without filling}{83} +\entry {Ragged right, with filling}{84} +\entry {Ragged right, without filling}{83} +\entry {Raising and lowering sections}{51} +\entry {Raw formatter commands}{146} +\entry {Raw HTML}{213} +\entry {raw text output}{188} +\initial {Q} +\entry {Quotation characters (`'), in source}{114} +\entry {Quotation marks, French}{115} +\entry {Quotation marks, German}{115} +\entry {Quotation marks, inserting}{114} +\entry {Quotations}{78} +\entry {Quotations in smaller fonts}{82} +\entry {Quote characters, inserting}{110} +\entry {Quoting, automatic for some macros}{156} +\initial {R} +\entry {RCS $Id}{253} +\entry {Recommended names for keys}{69} +\entry {Rectangle, black in hardcopy}{174} +\entry {Recursive macro invocations}{155} +\entry {Reducing font size}{75} +\entry {Reference implementation}{178} +\entry {Reference to @-commands}{223} +\entry {References}{53} +\entry {References using \code {@inforef}}{62} +\finishindex + +@section Index page break not before initial + +The next index is to show the bottoms of columns when the next page +doesn't start with an initial. + +@commenceindex +\initial {P} +\entry {\code {PACKAGE}}{196} +\entry {\code {PACKAGE_AND_VERSION}}{196} +\entry {\code {PACKAGE_NAME}}{196} +\entry {\code {PACKAGE_URL}}{196} +\entry {\code {PACKAGE_VERSION}}{196} +\entry {Page breaks, awkward}{124} +\entry {Page breaks, forcing}{126} +\entry {Page delimiter in Texinfo mode}{261} +\entry {Page headings}{270} +\entry {Page numbering}{270} +\entry {Page sizes for books}{175} +\entry {Page sizes, customized}{175} +\entry {\code {page-delimiter}}{261} +\entry {Pages, starting odd}{29} +\entry {Paper size, A4}{175} +\entry {Paragraph indentation control}{31} +\entry {Paragraph, marking text within}{66} +\entry {\code {paragraphindent}}{187} +\entry {Parameters to macros}{154} +\entry {Parentheses in node name}{37} +\entry {Parsing errors}{202} +\entry {Part of file formatting and printing}{266} +\entry {Part pages}{50} +\entry {Partial documents, formatting}{168} +\entry {Parts of a cross reference}{54} +\entry {Parts of a master menu}{28} +\entry {Parts of a menu}{43} +\entry {Patches, contributing}{4} +\entry {PCL file, for printing}{170} +\entry {\code {pdf image inclusions}}{97} +\entry {PDF output}{176} +\entry {PDF output of urls}{64} +\entry {PDF output, overview}{5} +\entry {\code {pdfetex}}{167} +\entry {\code {pdftex}}{176} +\entry {\code {pdftex\r {, and images}}}{97} +\entry {\code {pdftxei2dvi}}{166} +\entry {Period in node name}{37} +\entry {Periods, inserting}{111} +\entry {Perl format strings for translation}{199} +\entry {Perl POD, converting to Texinfo}{200} +\entry {Permissions text, including}{22} +\entry {Permissions, printed}{25} +\entry {\code {pg} (program) index}{102} +\entry {Picas}{98} +\entry {Pictures, inserting}{97} +\entry {Pinard, Fran\,{c}ois}{7} +\entry {Plain \TeX {}}{146} +\entry {Plain text output with \option {--plaintext}}{183} +\entry {Plain text output, overview}{4} +\entry {\code {png image format}}{97} +\entry {POD, converting to Texinfo}{200} +\entry {\code {pod2texi}}{200} +\entry {Point, indicating in a buffer}{121} +\entry {Pointer creation with \code {makeinfo}}{40} +\entry {Pointer validation with \code {makeinfo}}{185} +\entry {Pointer validation, suppressing}{168} +\entry {Pointer validation, suppressing from command line}{182} +\entry {Points (dimension)}{98} +\entry {PostScript output, overview}{4} +\entry {Pounds symbol}{118} +\entry {\code {PRE_ABOUT}}{192} +\entry {\code {PRE_BODY_CLOSE}}{192} +\entry {Preamble, in Info format}{283} +\entry {Predefined names for indices}{105} +\entry {Preface, etc., and Docbook}{48} +\entry {\code {PREFIX}}{196} +\entry {Preparing for \TeX {}}{173} +\entry {Preserving HTML links to old nodes}{221} +\entry {Prev node of Top node}{38} +\entry {Preventing first paragraph indentation}{32} +\entry {Preventing line and page breaks}{124} +\entry {Print and format in Texinfo mode}{170} +\entry {Print, format from Emacs shell}{170} +\entry {Printed book and manual characteristics}{6} +\entry {Printed output, indicating}{120} +\entry {Printed output, through \command {texi2any}}{185} +\entry {Printed permissions}{25} +\entry {Printing a region or buffer}{266} +\entry {Printing an index}{104} +\entry {Printing cost, reducing}{75} +\entry {Printing cropmarks}{176} +\entry {Printing DVI files, on MS-DOS/MS-Windows}{170} +\entry {Printing hardcopy}{166} +\entry {Problems, catching}{275} +\entry {\code {PROGRAM}}{196} +\entry {Program names, indicating}{72} +\entry {\code {PROGRAM_NAME_IN_FOOTER}}{192} +\entry {Programming, glyhs for}{119} +\entry {Pronunciation of Texinfo}{3} +\entry {Prototype row, column widths defined by}{93} +\initial {Q} +\entry {Quotation characters (`'), in source}{114} +\entry {Quotation marks, French}{115} +\entry {Quotation marks, German}{115} +\entry {Quotation marks, inserting}{114} +\entry {Quotations}{78} +\entry {Quotations in smaller fonts}{82} +\entry {Quote characters, inserting}{110} +\entry {Quoting, automatic for some macros}{156} +\entry {Ragged left, without filling}{83} +\entry {Ragged right, with filling}{84} +\entry {Ragged right, without filling}{83} +\entry {Raising and lowering sections}{51} +\entry {Raw formatter commands}{146} +\entry {Raw HTML}{213} +\entry {raw text output}{188} +\entry {RCS $Id}{253} +\entry {Recommended names for keys}{69} +\entry {Rectangle, black in hardcopy}{174} +\entry {Recursive macro invocations}{155} +\entry {Reducing font size}{75} +\entry {Reference implementation}{178} +\entry {Reference to @-commands}{223} +\entry {References}{53} +\entry {References using \code {@inforef}}{62} +\entry {Raw formatter commands}{146} +\entry {Raw HTML}{213} +\entry {raw text output}{188} +\entry {RCS $Id}{253} +\entry {Recommended names for keys}{69} +\entry {Rectangle, black in hardcopy}{174} +\entry {Recursive macro invocations}{155} +\entry {Reducing font size}{75} +\entry {Reference implementation}{178} +\entry {Reference to @-commands}{223} +\entry {References}{53} +\entry {References using \code {@inforef}}{62} +\finishindex + +@section Short indices + +See following pages + +@commenceindex +\initial{A} +\entry{aaaa}{1} +\initial{B} +\entry{bbbb}{2} +\finishindex + +If the above is in two columns, check that the space below the initials +`A' and `B' is even. + +@commenceindex +\initial{A} +\entry{aaaa}{1} +\initial{B} +\entry{bbbb}{2} +\initial{C} +\entry{cccc}{2} +\finishindex + +@commenceindex +\initial{A} +\entry{aaaa}{1} +\initial{B} +\entry{bbbb}{2} +\initial{C} +\entry{cccc}{2} +\entry{cccc}{2} +\finishindex + +@commenceindex +\initial{A} +\entry{aaaa}{1} +\entry{bbbb}{2} +\entry{bbbb}{2} +\entry{bbbb}{2} +\entry{bbbb}{2} +\entry{bbbb}{2} +\finishindex + +@commenceindex +\initial{A} +\entry{aaaa}{1} +\entry{bbbb}{2} +\entry{bbbb}{2} +\entry{bbbb}{2} +\entry{bbbb}{2} +\entry{bbbb}{2} +\entry{bbbb}{2} +\entry{cccc}{17} +\finishindex + +@section Final page of index hard to balance + +No empty page should appear in the middle of the index. All index +material should fit on the page within the margins. + +@commenceindex +\entry {outline, importing into}{39} +\entry {outline, inserting into}{39} +\entry {outline, label separator}{35} +\entry {outline, label type}{35} +\entry {outline, mailing}{37} +\entry {outline, motion}{38} +\entry {outline, overview}{40} +\entry {outline, show levels}{40} +\entry {outline, showing}{40} +\entry {outline, top-level}{40} +\entry {outline, view specs}{41} +\entry {outline, viewing}{40} +\entry {outliner}{32} +\entry {outliner commands}{33} +\entry {outliner keys}{90} +\entry {overview}{40} +\initial {P} +\entry {paragraph, filling}{38} +\entry {Paste Key}{8} +\entry {paste region}{11} +\entry {pasting a region}{70, 71, 76} +\entry {patch output}{15} +\entry {pathname}{15} +\entry {permanent identifier}{32, 36} +\entry {pipe character}{41} +\entry {posting buttons}{23} +\entry {posting news}{24} +\entry {programming interface}{57} +\entry {promotion}{36} +\entry {proportional scrolling}{62, 74} +\initial {R} +\entry {rdb-mode}{77} +\entry {README file}{65} +\entry {reference}{16} +\entry {refilling}{38} +\entry {region selection}{11} +\entry {region, active}{72} +\entry {relative autonumber}{32} +\entry {relative identifier}{35} +\entry {remote file}{15} +\entry {remote path}{15} +\entry {remote pathnames}{68} +\entry {remove lines}{27} +\entry {removing Hyperbole menu}{25} +\entry {Request For Comment}{15, 16} +\entry {restoring windows}{50} +\entry {RFC}{15, 16} +\entry {Rmail}{23} +\entry {rolo}{44} +\entry {rolo address}{14} +\entry {rolo commands}{45} +\entry {rolo entry}{44} +\entry {rolo file}{44} +\entry {rolo keys}{47} +\entry {rolo menu}{45} +\entry {rolo searching}{46} +\entry {rolo, buttons in}{44} +\entry {rolo, datestamps}{48} +\entry {rolo, editing}{48} +\entry {rolo, extending a match}{47} +\entry {rolo, finding matches}{47} +\entry {rolo, highlighting matches}{47, 49} +\entry {rolo, interactive searching}{47} +\entry {rolo, locating a name}{47} +\entry {rolo, moving through matches}{47} +\entry {rolo, moving to entries}{48} +\entry {rolo, outlining}{47} +\entry {rolo, personal}{48} +\entry {rolo, quitting}{48} +\entry {root cell}{34, 36} +\initial {S} +\entry {save lines}{27} +\entry {saving window configurations}{50} +\entry {screen}{29} +\entry {Screen}{62} +\entry {scrolling}{62, 74} +\entry {search}{26, 69} +\entry {searching, rolo}{46} +\entry {selection}{11} +\entry {set}{70, 76} +\entry {setting the view spec}{41} +\entry {sexp selection}{11} +\entry {SGML tag pair}{11} +\entry {show subtree}{40} +\entry {show tree}{40} +\entry {showing}{40} +\entry {side drag}{71} +\entry {signatures, hiding}{14} +\entry {site initialization}{66} +\entry {Smart Key}{8, 62, 99} +\entry {smart key assignments}{8} +\entry {smart key commands}{8} +\entry {Smart Key help}{11} +\entry {Smart Key operation}{9} +\entry {Smart Key, default context}{11, 89} +\entry {Smart Keyboard Keys}{73} +\entry {smart marking}{11} +\entry {Smart Menu}{74} +\entry {Smart Mouse Key}{70, 76} +\entry {Smart Mouse Key drag}{22} +\entry {Smart Mouse Key toggle}{8} +\entry {Smart Mouse Keys}{70} +\entry {smart selection}{11} +\entry {source line}{15} +\entry {splitting a cell}{39} +\entry {stack frame}{15} +\entry {star outline}{39} +\entry {starting Hyperbole}{65} +\entry {storage manager}{56} +\entry {string}{70, 76} +\entry {submenus}{27} +\entry {submodes}{29} +\entry {subtree, hide}{40} +\entry {subtree, show}{40} +\entry {swapping}{31} +\entry {system encapsulation}{57} +\initial {T} +\entry {table of contents}{16, 19} +\entry {tabs, inserting}{37} +\entry {tag}{16} +\entry {tags file}{16} +\entry {TAGS file}{16} +\entry {tar archive}{66} +\entry {tar archive browsing}{87} +\entry {terminal use}{4} +\entry {Texinfo cross-reference}{14} +\entry {Texinfo manual}{65} +\entry {text file}{39} +\entry {thing}{70, 76} +\entry {things}{11} +\entry {toc action type}{19} +\entry {toc implicit button type}{16} +\entry {toggling blank lines}{41} +\entry {top-level cell}{34, 36} +\entry {top-level view}{40} +\entry {Tramp}{15, 68} +\entry {transposing cells}{38} +\entry {tree, copying}{37} +\entry {tree, demoting}{36} +\entry {tree, exporting}{37} +\entry {tree, filling}{38} +\entry {tree, hide subtree}{40} +\entry {tree, killing}{36} +\entry {tree, mailing}{37} +\entry {tree, moving}{37} +\entry {tree, promoting}{36} +\entry {tree, show}{40} +\entry {tree, show subtree}{40} +\entry {type definition}{53} +\entry {type redefinition}{19, 53} +\initial {U} +\entry {unburying}{30} +\entry {uncompressing archives}{66} +\entry {UNIX manual}{15} +\entry {unpacking archives}{66} +\entry {URL}{14, 19, 87} +\entry {URLs, abbreviated}{68} +\entry {URLs, using with find-file}{68} +\entry {USENET}{23, 24} +\initial {V} +\entry {variables}{52} +\entry {vector}{70, 76} +\entry {version description}{98} +\entry {vertical drag}{72} +\entry {view}{40} +\entry {view mode}{75} +\entry {view spec}{41} +\entry {view spec klink}{42} +\entry {view spec, all lines and levels}{41} +\entry {view spec, blank lines}{41} +\entry {view spec, changing}{41} +\entry {view spec, characters}{41} +\entry {view spec, ellipses}{41} +\entry {view spec, example}{41} +\entry {view spec, label type}{41} +\entry {view spec, lines per cell}{41} +\entry {view spec, setting}{41} +\entry {view spec, show levels}{41} +\entry {VM}{23} +\initial {W} +\entry {W3}{87} +\entry {wconfig commands}{50} +\entry {web pages, displaying}{68} +\entry {window configuration commands}{50} +\entry {window configuration ring}{50} +\entry {window configurations}{50} +\entry {window control}{29} +\entry {window system}{68} +\entry {windows}{58} +\entry {word wrap}{38} +\entry {world-wide web}{87} +\entry {World-wide Web}{14, 19} +\entry {wrolo}{44} +\entry {wrolo commands}{45} +\entry {wrolo matches}{88} +\entry {wrolo menu}{47} +\entry {WWW}{14, 19} +\initial {X} +\entry {xdb}{15} +\entry {XEmacs}{2, 25} +\entry {XEmacs support}{69} +\initial {Y} +\entry {yank region}{11} +\entry {yank, reformatting}{53} +\entry {yanking}{70, 71, 76} +\initial {Z} +\entry {zcat}{66} +\entry {zip file}{66} +\entry {zooming}{31} +\finishindex + +@section Final page initial at top of both columns + +@commenceindex +\initial {P} +\entry {\code {phi}}{397} +\entry {\code {pi}}{397} +\entry {\code {pi-over-180}}{397} +\entry {\code {pi-over-2}}{397} +\entry {\code {pi-over-4}}{397} +\entry {\code {polar-complexp}}{392} +\entry {\code {poly-mix}}{408} +\entry {\code {poly-mul}}{408} +\entry {\code {poly-simplify}}{408} +\entry {\code {polynomial-base}}{408} +\entry {\code {polynomial-p}}{408} +\entry {\code {posp}}{391} +\entry {\code {pow}}{397} +\entry {\code {pow-mod}}{398} +\entry {\code {power-of-2}}{398} +\entry {\code {prime-test}}{399} +\entry {\code {primp}}{393} +\initial {Q} +\entry {\code {quarter-circle}}{397} +\entry {\code {quarter-integer}}{399} +\entry {\code {quotient}}{397} +\initial {R} +\entry {\code {random-digit}}{398} +\entry {\code {random-digits}}{399} +\entry {\code {random-float}}{399} +\entry {\code {ratp}}{392} +\entry {\code {read-expr}}{409} +\entry {\code {read-exprs}}{410} +\entry {\code {read-number}}{409} +\entry {\code {realp}}{392} +\entry {\code {rect-complexp}}{392} +\entry {\code {reduce-cols}}{400} +\entry {\code {reduce-vec}}{400} +\entry {\code {reject-arg}}{394} +\entry {\code {remove-units}}{409} +\entry {\code {rewrite}}{405} +\entry {\code {rewrite-heads}}{405} +\entry {\code {row-matrix}}{400} +\initial {S} +\entry {\code {scalarp}}{392} +\entry {\code {scale-int}}{396} +\entry {\code {scale-rounding}}{396} +\entry {\code {simplify}}{403} +\entry {\code {simplify-extended}}{403} +\entry {\code {simplify-units}}{403} +\entry {\code {single-units-in-expr-p}}{409} +\entry {\code {solve-eqn}}{407} +\entry {\code {solve-for}}{406} +\entry {\code {solve-system}}{407} +\entry {\code {sort-intv}}{396} +\entry {\code {sqr}}{397} +\entry {\code {sqrt-e}}{397} +\entry {\code {sqrt-two-pi}}{397} +\entry {\code {square-matrixp}}{393} +\entry {\code {swap-rows}}{401} +\initial {T} +\entry {\code {tderiv}}{406} +\entry {\code {to-fraction}}{399} +\entry {\code {to-hms}}{398} +\entry {\code {to-radians}}{398} +\entry {\code {to-radians-2}}{398} +\entry {\code {to-simple-fraction}}{399} +\entry {\code {to-standard-units}}{409} +\entry {\code {transpose}}{401} +\entry {\code {two-pi}}{397} +\initial {U} +\entry {\code {underflow}}{394} +\entry {\code {units-in-expr-p}}{409} +\initial {V} +\entry {\code {vec-length}}{399} +\entry {\code {vectorp}}{393} +\initial {W} +\entry {\code {with-extra-prec}}{395} +\initial {Z} +\entry {\code {zerop}}{391} +\finishindex + +@section Medium length index + +Check that no blank pages appear and that index text fits within page +margins. The text of the index is not short enough to fit on the page +after the text before the index. + +@page + + +Text before index. + +More text before index. + +More text before index. + +More text before index. + +More text before index. + +More text before index. + +More text before index. + +More text before index. + +More text before index. + + +@commenceindexnopage +\entry {\code {ac_cv_alignof_\var {type-or-expr}}}{152} +\entry {\code {ac_cv_c_const}}{157} +\entry {\code {ac_cv_c_int16_t}}{178} +\entry {\code {ac_cv_c_int32_t}}{179} +\entry {\code {ac_cv_c_int64_t}}{179} +\entry {\code {ac_cv_c_int8_t}}{178} +\entry {\code {ac_cv_c_restrict}}{157} +\entry {\code {ac_cv_c_uint16_t}}{180} +\entry {\code {ac_cv_c_uint32_t}}{180} +\entry {\code {ac_cv_c_uint64_t}}{180} +\entry {\code {ac_cv_c_uint8_t}}{180} +\entry {\code {ac_cv_f77_compiler_gnu}}{191} +\entry {\code {ac_cv_f77_dummy_main}}{193} +\entry {\code {ac_cv_f77_implicit_none}}{198} +\entry {\code {ac_cv_f77_libs}}{193} +\entry {\code {ac_cv_f77_main}}{194} +\entry {\code {ac_cv_f77_mangling}}{194} +\entry {\code {ac_cv_fc_check_bounds}}{198} +\entry {\code {ac_cv_fc_compiler_gnu}}{192} +\entry {\code {ac_cv_fc_dummy_main}}{193} +\entry {\code {ac_cv_fc_fixedform}}{197} +\entry {\code {ac_cv_fc_freeform}}{197} +\entry {\code {ac_cv_fc_implicit_none}}{198} +\entry {\code {ac_cv_fc_libs}}{193} +\entry {\code {ac_cv_fc_line_length}}{197} +\entry {\code {ac_cv_fc_main}}{194} +\entry {\code {ac_cv_fc_mangling}}{194} +\entry {\code {ac_cv_fc_module_ext}}{198} +\entry {\code {ac_cv_fc_module_flag}}{198} +\entry {\code {ac_cv_fc_module_output_flag}}{199} +\entry {\code {ac_cv_fc_pp_define}}{196} +\entry {\code {ac_cv_fc_pp_srcext_\var {ext}}}{196} +\entry {\code {ac_cv_fc_srcext_\var {ext}}}{196} +\entry {\code {ac_cv_file_\var {file}}}{91} +\entry {\code {ac_cv_func_chown_works}}{160} +\entry {\code {ac_cv_func_closedir_void}}{160} +\entry {\code {ac_cv_func_fnmatch_gnu}}{161} +\entry {\code {ac_cv_func_fnmatch_works}}{161, 166} +\entry {\code {ac_cv_func_\var {function}}}{166} +\entry {\code {ac_cv_func_getgroups_works}}{161} +\entry {\code {ac_cv_func_getpgrp_void}}{162} +\entry {\code {ac_cv_func_lstat_dereferences_slashed_symlink}}{163} +\entry {\code {ac_cv_func_lstat_empty_string_bug}}{165} +\entry {\code {ac_cv_func_malloc_0_nonnull}}{163} +\entry {\code {ac_cv_func_mbrtowc}}{163} +\entry {\code {ac_cv_func_memcmp_working}}{163} +\entry {\code {ac_cv_func_mmap_fixed_mapped}}{164} +\entry {\code {ac_cv_func_obstack}}{164} +\entry {\code {ac_cv_func_pow}}{165} +\entry {\code {ac_cv_func_realloc_0_nonnull}}{164} +\entry {\code {ac_cv_func_setpgrp_void}}{164} +\entry {\code {ac_cv_func_stat_empty_string_bug}}{165} +\entry {\code {ac_cv_func_strcoll_works}}{165} +\entry {\code {ac_cv_func_strerror_r_char_p}}{165} +\entry {\code {ac_cv_func_strnlen_working}}{166} +\entry {\code {ac_cv_func_strtod}}{165} +\entry {\code {ac_cv_func_strtold}}{165} +\entry {\code {ac_cv_func_utime_null}}{166} +\entry {\code {ac_cv_func_working_mktime}}{164} +\entry {\code {ac_cv_have_decl_\var {symbol}}}{175} +\entry {\code {ac_cv_header_\var {header-file}}}{174} +\entry {\code {ac_cv_header_stdbool_h}}{170, 172} +\entry {\code {ac_cv_header_stdc}}{172} +\entry {\code {ac_cv_header_sys_wait_h}}{172} +\entry {\code {ac_cv_header_time}}{424} +\entry {\code {ac_cv_lib_error_at_line}}{160} +\entry {\code {ac_cv_lib_\var {library}_\var {function}}}{91} +\entry {\code {ac_cv_member_\var {aggregate}_\var {member}}}{177} +\entry {\code {ac_cv_member_struct_stat_st_blocks}}{177} +\entry {\code {ac_cv_path_install}}{85} +\entry {\code {ac_cv_path_mkdir}}{86} +\entry {\code {ac_cv_path_SED}}{88} +\entry {\code {ac_cv_path_\var {variable}}}{90} +\entry {\code {ac_cv_prog_AWK}}{85} +\entry {\code {ac_cv_prog_c_openmp}}{153} +\entry {\code {ac_cv_prog_cc_\var {compiler}_c_o}}{156} +\entry {\code {ac_cv_prog_cc_stdc}}{155} +\entry {\code {ac_cv_prog_cxx_openmp}}{153} +\entry {\code {ac_cv_prog_EGREP}}{85} +\entry {\code {ac_cv_prog_f77_c_o}}{192} +\entry {\code {ac_cv_prog_f77_g}}{191} +\entry {\code {ac_cv_prog_f77_openmp}}{153} +\entry {\code {ac_cv_prog_f77_v}}{193} +\entry {\code {ac_cv_prog_fc_c_o}}{192} +\entry {\code {ac_cv_prog_fc_g}}{192} +\entry {\code {ac_cv_prog_fc_openmp}}{153} +\entry {\code {ac_cv_prog_fc_v}}{193} +\entry {\code {ac_cv_prog_FGREP}}{85} +\entry {\code {ac_cv_prog_GREP}}{85} +\entry {\code {ac_cv_prog_LEX}}{87} +\entry {\code {ac_cv_prog_\var {variable}}}{88, 89} +\entry {\code {ac_cv_prog_YACC}}{88} +\entry {\code {ac_cv_search_\var {function}}}{92} +\entry {\code {ac_cv_search_getmntent}}{162} +\entry {\code {ac_cv_sizeof_\var {type-or-expr}}}{152} +\entry {\code {ac_cv_sys_posix_termios}}{96} +\entry {\code {ac_cv_type_getgroups}}{178} +\entry {\code {ac_cv_type_long_double}}{179} +\entry {\code {ac_cv_type_long_double_wider}}{179} +\entry {\code {ac_cv_type_long_long_int}}{179} +\entry {\code {ac_cv_type_mbstate_t}}{179} +\entry {\code {ac_cv_type_mode_t}}{179} +\entry {\code {ac_cv_type_off_t}}{179} +\entry {\code {ac_cv_type_pid_t}}{179} +\entry {\code {ac_cv_type_size_t}}{180} +\entry {\code {ac_cv_type_ssize_t}}{180} +\entry {\code {ac_cv_type_\var {type}}}{180} +\entry {\code {ac_cv_type_uid_t}}{180} +\entry {\code {ac_cv_type_unsigned_long_long_int}}{180} +\finishindex + + + + + +@section Test of index widow elimination + +First time shows without widow elimination. Second time shows it with +(uses @file{texinfo-tex-test.WIDOWs} file). For test to work properly, +@code{ordm} should be a widow in the first case, and not in the second +case. + +@commenceindex +\input texinfo-tex-test.WIDOWs +\finishindex + + +@page + +@printindex WIDOW + + +@section Non-alphanumeric Index Initials + +/ and \ should be mirror images. + +@commenceindex +\initial{\\} +\initial{/} +\initial{|} +\initial{\{} +\initial{\}} +\initial{F} +\finishindex + + + +@part Another part@*Note no headline on this page + +@chapter First chapter after a part page + +Have a look at the headline. + + +@chapter Test of non-alphanumeric characters + +Not in code: @{@}@@#\ + +In code @t{@{@}@@#\} + + +@chapter Test of auxiliary files + +Need to test with @command{texi2dvi}. + +Undefined value in anchor: @anchor{@value{ho} ho} + +Xref to said anchor: @xref{@value{ho} ho}. + +@set auxvalue this is the value +Defined value in anchor: @anchor{@value{auxvalue} ho} + +Xref to said anchor: @xref{@value{auxvalue} ho}. (Should definitely +work.) + +@defindex ax + +value in index entry +@axindex @value{ho} in index entry + +defined value in index entry (this should definitely work) +@axindex @value{auxvalue} in index entry + +value in index entry, but only defined afterwards +@axindex @value{definedafter} index entry + +@axindex @b{another} + +some more text. + +test of macro in index entry: +@macro MyMac {arg} +ffff\arg\ggggg +@end macro + +@axindex @MyMac{bah} + +@page + +@set definedafter Defining this now +@set definedafter Defining this again + +@printindex ax + +@section Test of macros with @samp{@@} in index + +@defindex BB + +@macro Mac {arg} +\arg\@} +@end macro + +@macro MacTwo {arg} +@{@} +@end macro + +@BBindex @Mac{CCCC @@} + +@BBindex @MacTwo{DDDD @@} +@printindex BB + + +@section Test of @code{@@synindex} + +@defindex foo +@defindex bar + +@synindex foo bar + +@fooindex One +@barindex Two + +Should be two entries, not one below. + +@printindex bar + + +@section Test of index sort keys + +@defindex SK + +@SKindex @sortas{A} bbbbbbb (first) +@SKindex @sortas{B} aaaaaaa (second) + +@printindex SK + + +@chapter @code{@@set} and @code{@@value} + +@section Another test of @t{@@value} + +Underscores and hyphens in value + +@set foo-bar_ neenaw + +The value is @value{foo-bar_}. + + +@chapter Cross-references + +@section Comma insertion + +Check commas surrounding page number: + +@noindent +@xref{Target}, for more information (@code{@@xref})@* +@xref{Target} for more information@* +@xref{Target} for more information@* +@xref{Target} +for more information@* +@xref{Target}.@* +@xref{Target}@ for more info.@* +@xref{Target}@ +for more info.@* +@xref{Target}@* +for more info.@* +@xref{Target}@ for more info.@* +@xref{Target} --- for more info. (comma)@* +@xref{Target}@: --- for more info. (no comma)@* +See @ref{Target}, for more information (@code{@@ref})@* +See @ref{Target} for more information@* +See @ref{Target}.@* +(@pxref{Target}) (@code{@@pxref})@* +(@pxref{Target,, Hurricanes}) + + +@node Target +@section Target + +@section Non-existent target + +@xref{blllllllrrrrrrghhh}. + +@chapter Copying and captions + +@section Copying + +@documentencoding UTF-8 + +@copying +This manual is for blah-de-blah.@* +Backslash \@* + +Copyrite @copyright{} 201X@* +þ þ þ þ þ þ þ þ +@end copying + +Now for the @@insertcopying: + +@insertcopying + + +@section Captions + + +There's a float in this section. + +@float Figure,fig:ex1 +This is a float. + +@caption{This is a caption. +Multiple paragraphs are allowed here. Here are some ``special'' +characters: \ à. + +Paragraph breaks allowed. +} + +@shortcaption{short caption text.} + +This float should have a caption somewhere. +@end float + +List of floats now: + +@listoffloats Figure + + + + +@chapter Document encoding + +@documentencoding UTF-8 + + +Test of a few UTF-8 sequences. + +∃x∈X, x < ∞, s.t. x ∧ y + +A∩B=C + +(spacing here doesn't matter because we're not in math mode) + +Greek text: + +Η Πρώτη σύνοδος της Κωνσταντινούπολης, γνωστή ως Β΄ οικουμενική, ήταν η +εκκλησιαστική σύνοδος που διενεργήθηκε το 381 μ.Χ. και συγκλήθηκε από +τον αυτοκράτορα Θεοδόσιο, μετά από προτροπή του Μελετίου Αντιοχείας. +Στόχος της ήταν η εκκλησιαστική ειρήνευση, αλλά και η «επίλυση των +αναφυέντων εν τη εκκλησία κρίσιμων θεολογικών και διοικητικών +προβλημάτων». + +(random text copied from Wikipedia) + +double accent --- ταΐζω + + +@section Test of characters in section title + +Check table of contents. + +For PDF output, check the bookmarks pane in the reader. +(Currently plain ASCII approximations are used for the UTF-8 encoding.) + +@section --- übersicht + +@section --- @"Ubersicht + +@section @{ @} @@ @{@ @} @arrow{} @atchar{} @lbracechar{} + +This section should be called ``@{ @} @@ @{ @} @arrow{} @@ @{''. + + + +@chapter PDF link colours + +For PDF only. + + +Check that +colour change continues on next page +for @acronym{URL} split across pages, +and doesn't change the colour of the heading line. + +Push down to end of page + +par + +@tex +\global\def\urlcolor{0.32 0.39 0.50}% +@end tex + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +par + +@uref{aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/ +aaaaa/bbbbb/aaaaa/bbbbb/} + +par + + + +@bye diff --git a/macros/texinfo/texinfo/doc/texinfo.tex b/macros/texinfo/texinfo/doc/texinfo.tex new file mode 100644 index 0000000000..5fe81b4c28 --- /dev/null +++ b/macros/texinfo/texinfo/doc/texinfo.tex @@ -0,0 +1,11676 @@ +% 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{2019-02-16.14} + +% +% Copyright 1985, 1986, 1988, 1990-2019 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 <https://www.gnu.org/licenses/>. +% +% As a special exception, when this file is read by TeX when processing +% a Texinfo source document, you may use the result without +% restriction. This 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: +% https://ftp.gnu.org/gnu/texinfo/ (the Texinfo release area), or +% https://ftpmirror.gnu.org/texinfo/ (same, via a mirror), or +% https://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 https://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} + +% LaTeX's \typeout. This ensures that the messages it is used for +% are identical in format to the corresponding ones from latex/pdflatex. +\def\typeout{\immediate\write17}% + +\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\ptexsp=\sp +\let\ptexstar=\* +\let\ptexsup=\sup +\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 + +% Give the space character the catcode for a space. +\def\spaceisspace{\catcode`\ =10\relax} + +% Likewise for ^^M, the end of line character. +\def\endlineisspace{\catcode13=10\relax} + +\chardef\dashChar = `\- +\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 +} + +% 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} + +% Output routine +% + +% 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 } + +\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines +\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. + +% \domark is called twice inside \chapmacro, to add one +% mark before the section break, and one after. +% In the second call \prevchapterdefs is the same as \lastchapterdefs, +% and \prevsectiondefs is the same as \lastsectiondefs. +% Then if the page is not broken at the mark, some of the previous +% section appears on the page, and we can get the name of this section +% from \firstmark for @everyheadingmarks top. +% @everyheadingmarks bottom uses \botmark. +% +% See page 260 of The TeXbook. +\def\domark{% + \toks0=\expandafter{\lastchapterdefs}% + \toks2=\expandafter{\lastsectiondefs}% + \toks4=\expandafter{\prevchapterdefs}% + \toks6=\expandafter{\prevsectiondefs}% + \toks8=\expandafter{\lastcolordefs}% + \mark{% + \the\toks0 \the\toks2 % 0: marks for @everyheadingmarks top + \noexpand\or \the\toks4 \the\toks6 % 1: for @everyheadingmarks bottom + \noexpand\else \the\toks8 % 2: color marks + }% +} + +% \gettopheadingmarks, \getbottomheadingmarks, +% \getcolormarks - extract needed part of mark. +% +% \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\lastsection{} +\def\prevchapterdefs{} +\def\prevsectiondefs{} +\def\lastcolordefs{} + +% Margin to add to right of even pages, to left of odd pages. +\newdimen\bindingoffset +\newdimen\normaloffset +\newdimen\txipagewidth \newdimen\txipageheight + +% Main output routine. +% +\chardef\PAGE = 255 +\output = {\onepageout{\pagecontents\PAGE}} + +\newbox\headlinebox +\newbox\footlinebox + +% \onepageout takes a vbox as an argument. +% \shipout a vbox for a single page, adding an optional header, footer +% and footnote. This also causes index entries for this page to be written +% to the auxiliary files. +% +\def\onepageout#1{% + \hoffset=\normaloffset + % + \ifodd\pageno \advance\hoffset by \bindingoffset + \else \advance\hoffset by -\bindingoffset\fi + % + % Common context changes for both heading and footing. + % 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=\txipagewidth \texinfochars} + % + % Retrieve the information for the headings from the marks in the page, + % and call Plain TeX's \makeheadline and \makefootline, which use the + % values in \headline and \footline. + % + % This is used to check if we are on the first page of a chapter. + \ifcase1\topmark\fi + \let\prevchaptername\thischaptername + \ifcase0\firstmark\fi + \let\curchaptername\thischaptername + % + \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi + \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi + % + \ifx\curchaptername\prevchaptername + \let\thischapterheading\thischapter + \else + % \thischapterheading is the same as \thischapter except it is blank + % for the first page of a chapter. This is to prevent the chapter name + % being shown twice. + \def\thischapterheading{}% + \fi + % + \global\setbox\headlinebox = \vbox{\commmonheadfootline \makeheadline}% + \global\setbox\footlinebox = \vbox{\commmonheadfootline \makefootline}% + % + {% + % Set context for writing to auxiliary files like index files. + % 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{{\indexbackslash }acronym}{32}{\code {\acronym}} + % "\acronym" won't work when it's read back in; + % it needs to be + % {\code {{\backslashcurfont }acronym} + \shipout\vbox{% + % Do this early so pdf references go to the beginning of the page. + \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\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 + % + }% end of \shipout\vbox + }% end of group with \indexdummies + \advancepageno + \ifnum\outputpenalty>-20000 \else\dosupereject\fi +} + +\newinsert\margin \dimen\margin=\maxdimen + +% Main part of page, including any footnotes +\def\pagebody#1{\vbox to\txipageheight{\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} +} + + +% Argument parsing + +% 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. +% For example, \def\foo{\parsearg\fooxxx}. +% +\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. Also remove a @texinfoc +% comment (see \scanmacro for details). Pass the result on to \argcheckspaces. +\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm} +\def\argremovec#1\c#2\ArgTerm{\argremovetexinfoc #1\texinfoc\ArgTerm} +\def\argremovetexinfoc#1\texinfoc#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm} + +% Each occurrence of `\^^M' or `<space>\^^M' is replaced by a single space. +% +% \argremovec might leave us with trailing space, e.g., +% @end itemize @c foo +% This space token undergoes the same procedure and is eventually removed +% by \finishparsearg. +% +\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M} +\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M} +\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{% + \def\temp{#3}% + \ifx\temp\empty + % Do not use \next, perhaps the caller of \parsearg uses it; reuse \temp: + \let\temp\finishparsearg + \else + \let\temp\argcheckspaces + \fi + % Put the space token in: + \temp#1 #3\ArgTerm +} + +% If a _delimited_ argument is enclosed in braces, they get stripped; so +% to get _exactly_ the rest of the line, we had to prevent such situation. +% We prepended an \empty token at the very beginning and we expand it now, +% just before passing the control to \argtorun. +% (Similarly, we have to think about #3 of \argcheckspacesY above: it is +% either the null string, or it ends with \^^M---thus there is no danger +% that a pair of braces would be stripped. +% +% But first, we have to remove the trailing space token. +% +\def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}} + + +% \parseargdef - define a command taking an argument on the line +% +% \parseargdef\foo{...} +% is roughly equivalent to +% \def\foo{\parsearg\Xfoo} +% \def\Xfoo#1{...} +\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. + \addgroupbox + \prevdepth = \dimen1 + \checkinserts +} + +\def\addgroupbox{ + % \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 = \txipageheight \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\txipageheight + \page + \fi + \fi + \box\groupbox +} + +% +% 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 +} + +% @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\c{\begingroup \catcode`\^^M=\active% +\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other% +\cxxx} +{\catcode`\^^M=\active \gdef\cxxx#1^^M{\endgroup}} +% +\let\comment\c + +% @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 + +% @setfilename INFO-FILENAME - ignored +\let\setfilename=\comment + +% @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 +\newbox\boxB +\newcount\countA +\newif\ifpdf +\newif\ifpdfmakepagedest + +% +% For LuaTeX +% + +\newif\iftxiuseunicodedestname +\txiuseunicodedestnamefalse % For pdfTeX etc. + +\ifx\luatexversion\thisisundefined +\else + % Use Unicode destination names + \txiuseunicodedestnametrue + % Escape PDF strings with converting UTF-16 from UTF-8 + \begingroup + \catcode`\%=12 + \directlua{ + function UTF16oct(str) + tex.sprint(string.char(0x5c) .. '376' .. string.char(0x5c) .. '377') + for c in string.utfvalues(str) do + if c < 0x10000 then + tex.sprint( + string.format(string.char(0x5c) .. string.char(0x25) .. '03o' .. + string.char(0x5c) .. string.char(0x25) .. '03o', + (c / 256), (c % 256))) + else + c = c - 0x10000 + local c_hi = c / 1024 + 0xd800 + local c_lo = c % 1024 + 0xdc00 + tex.sprint( + string.format(string.char(0x5c) .. string.char(0x25) .. '03o' .. + string.char(0x5c) .. string.char(0x25) .. '03o' .. + string.char(0x5c) .. string.char(0x25) .. '03o' .. + string.char(0x5c) .. string.char(0x25) .. '03o', + (c_hi / 256), (c_hi % 256), + (c_lo / 256), (c_lo % 256))) + end + end + end + } + \endgroup + \def\pdfescapestrutfsixteen#1{\directlua{UTF16oct('\luaescapestring{#1}')}} + % Escape PDF strings without converting + \begingroup + \directlua{ + function PDFescstr(str) + for c in string.bytes(str) do + if c <= 0x20 or c >= 0x80 or c == 0x28 or c == 0x29 or c == 0x5c then + tex.sprint( + string.format(string.char(0x5c) .. string.char(0x25) .. '03o', + c)) + else + tex.sprint(string.char(c)) + end + end + end + } + \endgroup + \def\pdfescapestring#1{\directlua{PDFescstr('\luaescapestring{#1}')}} + \ifnum\luatexversion>84 + % For LuaTeX >= 0.85 + \def\pdfdest{\pdfextension dest} + \let\pdfoutput\outputmode + \def\pdfliteral{\pdfextension literal} + \def\pdfcatalog{\pdfextension catalog} + \def\pdftexversion{\numexpr\pdffeedback version\relax} + \let\pdfximage\saveimageresource + \let\pdfrefximage\useimageresource + \let\pdflastximage\lastsavedimageresourceindex + \def\pdfendlink{\pdfextension endlink\relax} + \def\pdfoutline{\pdfextension outline} + \def\pdfstartlink{\pdfextension startlink} + \def\pdffontattr{\pdfextension fontattr} + \def\pdfobj{\pdfextension obj} + \def\pdflastobj{\numexpr\pdffeedback lastobj\relax} + \let\pdfpagewidth\pagewidth + \let\pdfpageheight\pageheight + \edef\pdfhorigin{\pdfvariable horigin} + \edef\pdfvorigin{\pdfvariable vorigin} + \fi +\fi + +% 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. + \xdef#1{#1}% + \else + % The expandable \pdfescapestring primitive escapes parentheses, + % backslashes, and other special chars. + \xdef#1{\pdfescapestring{#1}}% + \fi +} +\def\txiescapepdfutfsixteen#1{% + \ifx\pdfescapestrutfsixteen\thisisundefined + % No UTF-16 converting macro available. + \txiescapepdf{#1}% + \else + \xdef#1{\pdfescapestrutfsixteen{#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 using ideas from 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. The dark red here is dark enough to print on paper as + % nearly black, but still distinguishable for online viewing. We use + % black by default, though. + \def\rgbDarkRed{0.50 0.09 0.12} + \def\rgbBlack{0 0 0} + % + % rg sets the color for filling (usual text, etc.); + % RG 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\setpdfdestname#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 + \makevalueexpandable + \turnoffactive + \iftxiuseunicodedestname + \ifx \declaredencoding \latone + % Pass through Latin-1 characters. + % LuaTeX with byte wise I/O converts Latin-1 characters to Unicode. + \else + \ifx \declaredencoding \utfeight + % Pass through Unicode characters. + \else + % Use ASCII approximations in destination names. + \passthroughcharsfalse + \fi + \fi + \else + % Use ASCII approximations in destination names. + \passthroughcharsfalse + \fi + \def\pdfdestname{#1}% + \txiescapepdf\pdfdestname + }} + % + \def\setpdfoutlinetext#1{{% + \indexnofonts + \makevalueexpandable + \turnoffactive + \ifx \declaredencoding \latone + % The PDF format can use an extended form of Latin-1 in bookmark + % strings. See Appendix D of the PDF Reference, Sixth Edition, for + % the "PDFDocEncoding". + \passthroughcharstrue + % Pass through Latin-1 characters. + % LuaTeX: Convert to Unicode + % pdfTeX: Use Latin-1 as PDFDocEncoding + \def\pdfoutlinetext{#1}% + \else + \ifx \declaredencoding \utfeight + \ifx\luatexversion\thisisundefined + % For pdfTeX with UTF-8. + % TODO: the PDF format can use UTF-16 in bookmark strings, + % but the code for this isn't done yet. + % Use ASCII approximations. + \passthroughcharsfalse + \def\pdfoutlinetext{#1}% + \else + % For LuaTeX with UTF-8. + % Pass through Unicode characters for title texts. + \passthroughcharstrue + \def\pdfoutlinetext{#1}% + \fi + \else + % For non-Latin-1 or non-UTF-8 encodings. + % Use ASCII approximations. + \passthroughcharsfalse + \def\pdfoutlinetext{#1}% + \fi + \fi + % LuaTeX: Convert to UTF-16 + % pdfTeX: Use Latin-1 as PDFDocEncoding + \txiescapepdfutfsixteen\pdfoutlinetext + }} + % + \def\pdfmkdest#1{% + \setpdfdestname{#1}% + \safewhatsit{\pdfdest name{\pdfdestname} xyz}% + } + % + % used to mark target names; must be expandable. + \def\pdfmkpgn#1{#1} + % + % by default, use black for everything. + \def\urlcolor{\rgbBlack} + \def\linkcolor{\rgbBlack} + \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. + \setpdfoutlinetext{#1} + \setpdfdestname{#3} + \ifx\pdfdestname\empty + \def\pdfdestname{#4}% + \fi + % + \pdfoutline goto name{\pdfmkpgn{\pdfdestname}}#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} + % \pdfgettoks - Surround page numbers in #1 with @pdflink. #1 may + % be a simple number, or a list of numbers in the case of an index + % entry. + \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 + +% +% For XeTeX +% +\ifx\XeTeXrevision\thisisundefined +\else + % + % XeTeX version check + % + \ifnum\strcmp{\the\XeTeXversion\XeTeXrevision}{0.99996}>-1 + % TeX Live 2016 contains XeTeX 0.99996 and xdvipdfmx 20160307. + % It can use the `dvipdfmx:config' special (from TeX Live SVN r40941). + % For avoiding PDF destination name replacement, we use this special + % instead of xdvipdfmx's command line option `-C 0x0010'. + \special{dvipdfmx:config C 0x0010} + % XeTeX 0.99995+ comes with xdvipdfmx 20160307+. + % It can handle Unicode destination names for PDF. + \txiuseunicodedestnametrue + \else + % XeTeX < 0.99996 (TeX Live < 2016) cannot use the + % `dvipdfmx:config' special. + % So for avoiding PDF destination name replacement, + % xdvipdfmx's command line option `-C 0x0010' is necessary. + % + % XeTeX < 0.99995 can not handle Unicode destination names for PDF + % because xdvipdfmx 20150315 has a UTF-16 conversion issue. + % It is fixed by xdvipdfmx 20160106 (TeX Live SVN r39753). + \txiuseunicodedestnamefalse + \fi + % + % Color support + % + \def\rgbDarkRed{0.50 0.09 0.12} + \def\rgbBlack{0 0 0} + % + \def\pdfsetcolor#1{\special{pdf:scolor [#1]}} + % + % 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 + } + % + % PDF outline support + % + % Emulate pdfTeX primitive + \def\pdfdest name#1 xyz{% + \special{pdf:dest (#1) [@thispage /XYZ @xpos @ypos null]}% + } + % + \def\setpdfdestname#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 + \makevalueexpandable + \turnoffactive + \iftxiuseunicodedestname + % Pass through Unicode characters. + \else + % Use ASCII approximations in destination names. + \passthroughcharsfalse + \fi + \def\pdfdestname{#1}% + \txiescapepdf\pdfdestname + }} + % + \def\setpdfoutlinetext#1{{% + \turnoffactive + % Always use Unicode characters in title texts. + \def\pdfoutlinetext{#1}% + % For XeTeX, xdvipdfmx converts to UTF-16. + % So we do not convert. + \txiescapepdf\pdfoutlinetext + }} + % + \def\pdfmkdest#1{% + \setpdfdestname{#1}% + \safewhatsit{\pdfdest name{\pdfdestname} xyz}% + } + % + % by default, use black for everything. + \def\urlcolor{\rgbBlack} + \def\linkcolor{\rgbBlack} + \def\endlink{\setcolor{\maincolor}\pdfendlink} + % + \def\dopdfoutline#1#2#3#4{% + \setpdfoutlinetext{#1} + \setpdfdestname{#3} + \ifx\pdfdestname\empty + \def\pdfdestname{#4}% + \fi + % + \special{pdf:out [-] #2 << /Title (\pdfoutlinetext) /A + << /S /GoTo /D (\pdfdestname) >> >> }% + } + % + \def\pdfmakeoutlines{% + \begingroup + % + % For XeTeX, counts of subentries are not necessary. + % Therefore, we read toc only once. + % + % We use node names as destinations. + \def\partentry##1##2##3##4{}% ignore parts in the outlines + \def\numchapentry##1##2##3##4{% + \dopdfoutline{##1}{1}{##3}{##4}}% + \def\numsecentry##1##2##3##4{% + \dopdfoutline{##1}{2}{##3}{##4}}% + \def\numsubsecentry##1##2##3##4{% + \dopdfoutline{##1}{3}{##3}{##4}}% + \def\numsubsubsecentry##1##2##3##4{% + \dopdfoutline{##1}{4}{##3}{##4}}% + % + \let\appentry\numchapentry% + \let\appsecentry\numsecentry% + \let\appsubsecentry\numsubsecentry% + \let\appsubsubsecentry\numsubsubsecentry% + \let\unnchapentry\numchapentry% + \let\unnsecentry\numsecentry% + \let\unnsubsecentry\numsubsecentry% + \let\unnsubsubsecentry\numsubsubsecentry% + % + % For XeTeX, xdvipdfmx converts strings to UTF-16. + % Therefore, the encoding and the language may not be considered. + % + \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[}]% + ] + + \special{pdf:docview << /PageMode /UseOutlines >> } + % ``\special{pdf:tounicode ...}'' is not necessary + % because xdvipdfmx converts strings from UTF-8 to UTF-16 without it. + % However, due to a UTF-16 conversion issue of xdvipdfmx 20150315, + % ``\special{pdf:dest ...}'' cannot handle non-ASCII strings. + % It is fixed by xdvipdfmx 20160106 (TeX Live SVN r39753). +% + \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 + } + % 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}% + \special{pdf:bann << /Border [0 0 0] + /Subtype /Link /A << /S /URI /URI (#1) >> >>}% + \endgroup} + \def\endlink{\setcolor{\maincolor}\special{pdf:eann}} + \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{% + \special{pdf:bann << /Border [0 0 0] + /Type /Annot /Subtype /Link /A << /S /GoTo /D (#1) >> >>}% + \setcolor{\linkcolor}#1\endlink} + \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st} +% + % + % @image support + % + % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto). + \def\doxeteximage#1#2#3{% + \def\xeteximagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}% + \def\xeteximageheight{#3}\setbox2 = \hbox{\ignorespaces #3}% + % + % XeTeX (and the PDF format) supports .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\xeteximgext=\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 + \errmessage{Could not find image file #1 for XeTeX}% + \else \gdef\xeteximgext{JPG}% + \fi + \else \gdef\xeteximgext{jpeg}% + \fi + \else \gdef\xeteximgext{jpg}% + \fi + \else \gdef\xeteximgext{png}% + \fi + \else \gdef\xeteximgext{PDF}% + \fi + \else \gdef\xeteximgext{pdf}% + \fi + \closein 1 + \endgroup + % + \def\xetexpdfext{pdf}% + \ifx\xeteximgext\xetexpdfext + \XeTeXpdffile "#1".\xeteximgext "" + \else + \def\xetexpdfext{PDF}% + \ifx\xeteximgext\xetexpdfext + \XeTeXpdffile "#1".\xeteximgext "" + \else + \XeTeXpicfile "#1".\xeteximgext "" + \fi + \fi + \ifdim \wd0 >0pt width \xeteximagewidth \fi + \ifdim \wd2 >0pt height \xeteximageheight \fi \relax + } +\fi + + +% +\message{fonts,} + +% 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\defsl\slshape{10}{\magstep1}{OT1TT} +\setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT} +\def\df{\let\ttfont=\deftt \let\bffont = \defbf +\let\ttslfont=\defttsl \let\slfont=\defsl \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 math mode superscripts (7pt). +\def\sevennominalsize{7pt} +\setfont\sevenrm\rmshape{7}{1000}{OT1} +\setfont\seventt\ttshape{10}{700}{OT1TT} +\setfont\sevenbf\bfshape{10}{700}{OT1} +\setfont\sevenit\itshape{7}{1000}{OT1IT} +\setfont\sevensl\slshape{10}{700}{OT1} +\setfont\sevensf\sfshape{10}{700}{OT1} +\setfont\sevensc\scshape{10}{700}{OT1} +\setfont\seventtsl\ttslshape{10}{700}{OT1TT} +\font\seveni=cmmi7 +\font\sevensy=cmsy7 +\def\sevenecsize{0700} + +% 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\secrmnotbold\rmshape{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 @acronym 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\defsl\slshape{10}{\magstephalf}{OT1TT} +\setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT} +\def\df{\let\ttfont=\deftt \let\bffont = \defbf +\let\slfont=\defsl \let\ttslfont=\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 math mode superscripts (7pt). +\def\sevennominalsize{7pt} +\setfont\sevenrm\rmshape{7}{1000}{OT1} +\setfont\seventt\ttshape{10}{700}{OT1TT} +\setfont\sevenbf\bfshape{10}{700}{OT1} +\setfont\sevenit\itshape{7}{1000}{OT1IT} +\setfont\sevensl\slshape{10}{700}{OT1} +\setfont\sevensf\sfshape{10}{700}{OT1} +\setfont\sevensc\scshape{10}{700}{OT1} +\setfont\seventtsl\ttslshape{10}{700}{OT1TT} +\font\seveni=cmmi7 +\font\sevensy=cmsy7 +\def\sevenecsize{0700} + +% 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 @acronym 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 + +% 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} + + +% 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 +} + +% +% 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 #1font\endcsname % change the current font +} + +\def\rm{\fam=0 \setfontstyle{rm}} +\def\it{\fam=\itfam \setfontstyle{it}} +\def\sl{\fam=\slfam \setfontstyle{sl}} +\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf} +\def\tt{\fam=\ttfam \setfontstyle{tt}} + +% Texinfo sort of supports the sans serif font style, which plain TeX does not. +% So we set up a \sf. +\newfam\sffam +\def\sf{\fam=\sffam \setfontstyle{sf}} + +% We don't need math for this font style. +\def\ttsl{\setfontstyle{ttsl}} + + +% In order for the font changes to affect most math symbols and letters, +% we have to define the \textfont of the standard families. +% We don't bother to reset \scriptscriptfont; awaiting user need. +% +\def\resetmathfonts{% + \textfont0=\rmfont \textfont1=\ifont \textfont2=\syfont + \textfont\itfam=\itfont \textfont\slfam=\slfont \textfont\bffam=\bffont + \textfont\ttfam=\ttfont \textfont\sffam=\sffont + % + % Fonts for superscript. Note that the 7pt fonts are used regardless + % of the current font size. + \scriptfont0=\sevenrm \scriptfont1=\seveni \scriptfont2=\sevensy + \scriptfont\itfam=\sevenit \scriptfont\slfam=\sevensl + \scriptfont\bffam=\sevenbf \scriptfont\ttfam=\seventt + \scriptfont\sffam=\sevensf +} + +% + +% The font-changing commands (all called \...fonts) redefine the meanings +% of \STYLEfont, 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 \STYLEfont to set the current font. +% +% The fonts used for \ifont are for "math italics" (\itfont is for italics +% in regular text). \syfont is also used in math mode only. +% +% Each font-changing command also sets the names \lsize (one size lower) +% and \lllsize (three sizes lower). These relative commands are used +% in, e.g., the LaTeX logo and acronyms. +% +% This all needs generalizing, badly. +% + +\def\assignfonts#1{% + \expandafter\let\expandafter\rmfont\csname #1rm\endcsname + \expandafter\let\expandafter\itfont\csname #1it\endcsname + \expandafter\let\expandafter\slfont\csname #1sl\endcsname + \expandafter\let\expandafter\bffont\csname #1bf\endcsname + \expandafter\let\expandafter\ttfont\csname #1tt\endcsname + \expandafter\let\expandafter\smallcaps\csname #1sc\endcsname + \expandafter\let\expandafter\sffont \csname #1sf\endcsname + \expandafter\let\expandafter\ifont \csname #1i\endcsname + \expandafter\let\expandafter\syfont \csname #1sy\endcsname + \expandafter\let\expandafter\ttslfont\csname #1ttsl\endcsname +} + +\newif\ifrmisbold + +% Select smaller font size with the current style. Used to change font size +% in, e.g., the LaTeX logo and acronyms. If we are using bold fonts for +% normal roman text, also use bold fonts for roman text in the smaller size. +\def\switchtolllsize{% + \expandafter\assignfonts\expandafter{\lllsize}% + \ifrmisbold + \let\rmfont\bffont + \fi + \csname\curfontstyle\endcsname +}% + +\def\switchtolsize{% + \expandafter\assignfonts\expandafter{\lsize}% + \ifrmisbold + \let\rmfont\bffont + \fi + \csname\curfontstyle\endcsname +}% + +\def\definefontsetatsize#1#2#3#4#5{% +\expandafter\def\csname #1fonts\endcsname{% + \def\curfontsize{#1}% + \def\lsize{#2}\def\lllsize{#3}% + \csname rmisbold#5\endcsname + \assignfonts{#1}% + \resetmathfonts + \setleading{#4}% +}} + +\definefontsetatsize{text} {reduced}{smaller}{\textleading}{false} +\definefontsetatsize{title} {chap} {subsec} {27pt} {true} +\definefontsetatsize{chap} {sec} {text} {19pt} {true} +\definefontsetatsize{sec} {subsec} {reduced}{17pt} {true} +\definefontsetatsize{ssec} {text} {small} {15pt} {true} +\definefontsetatsize{reduced}{small} {smaller}{10.5pt}{false} +\definefontsetatsize{small} {smaller}{smaller}{10.5pt}{false} +\definefontsetatsize{smaller}{smaller}{smaller}{9.5pt} {false} + +\def\titlefont#1{{\titlefonts\rm #1}} +\let\subsecfonts = \ssecfonts +\let\subsubsecfonts = \ssecfonts + +% 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. + +\let\currentmarkupstyle\empty + +\def\setupmarkupstyle#1{% + \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{% + \ifmonospace + \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax + \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax + '% + \else \char'15 \fi + \else \char'15 \fi + \else + '% + \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{% + \ifmonospace + \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 + \else + \relax`% + \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`\.=\@m \sfcode`\?=\@m \sfcode`\!=\@m + \sfcode`\:=\@m \sfcode`\;=\@m \sfcode`\,=\@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') aka @url 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. + +% TeX-only option to allow changing PDF output to show only the second +% arg (if given), and not the url (which is then just the link target). +\newif\ifurefurlonlylink + +% The main macro is \urefbreak, which allows breaking at expected +% places within the url. (There used to be another version, which +% didn't support automatic breaking.) +\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}% look for second arg + \ifdim\wd0 > 0pt + \ifpdf + % For pdfTeX and LuaTeX + \ifurefurlonlylink + % PDF plus option to not display url, show just arg + \unhbox0 + \else + % PDF, normally display both arg and url for consistency, + % visibility, if the pdf is eventually used to print, etc. + \unhbox0\ (\urefcode{#1})% + \fi + \else + \ifx\XeTeXrevision\thisisundefined + \unhbox0\ (\urefcode{#1})% DVI, always show arg and url + \else + % For XeTeX + \ifurefurlonlylink + % PDF plus option to not display url, show just arg + \unhbox0 + \else + % PDF, normally display both arg and url for consistency, + % visibility, if the pdf is eventually used to print, etc. + \unhbox0\ (\urefcode{#1})% + \fi + \fi + \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`\&=\active \catcode`\.=\active + \catcode`\#=\active \catcode`\?=\active + \catcode`\/=\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\urefprestretchamount{.13em} +\def\urefpoststretchamount{.1em} +\def\urefprestretch{\urefprebreak \hskip0pt plus\urefprestretchamount\relax} +\def\urefpoststretch{\urefpostbreak \hskip0pt plus\urefprestretchamount\relax} +% +\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 + \ifx\XeTeXrevision\thisisundefined + \let\email=\uref + \else + \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} + \fi +\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} + +% @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{% + {\switchtolsize #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{% + \ifmmode\else % only go into math if not in math mode already + \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 + % have to provide another name for sup operator + \let\mathopsup=\sup + $\expandafter\finishmath\fi +} +\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 + } +} + +% for @sub and @sup, if in math mode, just do a normal sub/superscript. +% If in text, use math to place as sub/superscript, but switch +% into text mode, with smaller fonts. This is a different font than the +% one used for real math sub/superscripts (8pt vs. 7pt), but let's not +% fix it (significant additions to font machinery) until someone notices. +% +\def\sub{\ifmmode \expandafter\sb \else \expandafter\finishsub\fi} +\def\finishsub#1{$\sb{\hbox{\switchtolllsize #1}}$}% +% +\def\sup{\ifmmode \expandafter\ptexsp \else \expandafter\finishsup\fi} +\def\finishsup#1{$\ptexsp{\hbox{\switchtolllsize #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. +\def\lbracechar{{\ifmonospace\char123\else\ensuremath\lbrace\fi}} +\def\rbracechar{{\ifmonospace\char125\else\ensuremath\rbrace\fi}} +\let\{=\lbracechar +\let\}=\rbracechar + +% @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{\switchtolllsize \underbar{a}}} +\def\ordm{\leavevmode\raise1ex\hbox{\switchtolllsize \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. + \switchtolllsize A% + \fi + }% + \vss + }}% + \kern-.15em + \TeX +} + +% Some math mode symbols. Define \ensuremath to switch into math mode +% unless we are already there. Expansion tricks may not be needed here, +% but safer, and can't hurt. +\def\ensuremath{\ifmmode \expandafter\asis \else\expandafter\ensuredmath \fi} +\def\ensuredmath#1{$\relax#1$} +% +\def\bullet{\ensuremath\ptexbullet} +\def\geq{\ensuremath\ge} +\def\leq{\ensuremath\le} +\def\minus{\ensuremath-} + +% @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 +% +{\ttfont \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 European Computer Modern fonts (cm-super in outline format) +% for non-CM glyphs. That is ec* for regular text and tc* for the text +% companion symbols (LaTeX TS1 encoding). Both are part of the ec +% package and follow the same conventions. +% +\def\ecfont{\etcfont{e}} +\def\tcfont{\etcfont{t}} +% +\def\etcfont#1{% + % 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 = #1ctt\ecsize \space at \nominalsize + \else + \ifx\curfontstyle\bfstylename + % bold: + \font\thisecfont = #1cb\ifusingit{i}{x}\ecsize \space at \nominalsize + \else + % regular: + \font\thisecfont = #1c\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{\switchtolllsize 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 + +% @setcontentsaftertitlepage used to do an implicit @contents or +% @shortcontents after @end titlepage, but it is now obsolete. +\def\setcontentsaftertitlepage{% + \errmessage{@setcontentsaftertitlepage has been removed as a Texinfo + command; move your @contents command if you want the contents + after the title page.}}% +\def\setshortcontentsaftertitlepage{% + \errmessage{@setshortcontentsaftertitlepage has been removed as a Texinfo + command; move your @shortcontents and @contents commands if you + want the contents after the title page.}}% + +\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 +} + +\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. \par should +% be specified before the end of the \vbox, since a vbox is a group. +% +\def\raggedtitlesettings{% + \rm + \hyphenpenalty=10000 + \parindent=0pt + \tolerance=5000 + \ptexraggedright +} + +% Macros to be used within @titlepage: + +\let\subtitlerm=\rmfont +\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\rm \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 \makeheadline and \makefootline in Plain 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\txipageheight 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 + +% These define \getoddheadingmarks, \getevenheadingmarks, +% \getoddfootingmarks, and \getevenfootingmarks, each to one of +% \gettopheadingmarks, \getbottomheadingmarks. +% +\def\evenheadingmarks{\headingmarks{even}{heading}} +\def\oddheadingmarks{\headingmarks{odd}{heading}} +\def\evenfootingmarks{\headingmarks{even}{footing}} +\def\oddfootingmarks{\headingmarks{odd}{footing}} +\parseargdef\everyheadingmarks{\headingmarks{even}{heading}{#1} + \headingmarks{odd}{heading}{#1} } +\parseargdef\everyfootingmarks{\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. + +\parseargdef\headings{\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{\thischapterheading\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{\thischapterheading\hfil\folio}} +\global\oddheadline={\line{\thischapterheading\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{\thischapterheading\hfil\folio}} +\global\let\contentsalignmacro = \chapoddpage +} + +\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} +\def\HEADINGSsinglex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapterheading\hfil\folio}} +\global\oddheadline={\line{\thischapterheading\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 so 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}% + % + \ifinner\else + \vadjust{\penalty 1200}% not good to break after first line of item. + \fi + % We can be in inner vertical mode in a footnote, although an + % @itemize looks awful there. + }% + \flushcr +} + +% \splitoff TOKENS\endmark defines \first to be the first token in +% TOKENS, and \rest to be the remainder. +% +\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}% + +% Allow an optional argument of an uppercase letter, lowercase letter, +% or number, to specify the first label in the enumerated list. No +% argument is the same as `1'. +% +\envparseargdef\enumerate{\enumeratey #1 \endenumeratey} +\def\enumeratey #1 #2\endenumeratey{% + % If we were given no argument, pretend we were given `1'. + \def\thearg{#1}% + \ifx\thearg\empty \def\thearg{1}\fi + % + % Detect if the argument is a single token. If so, it might be a + % letter. Otherwise, the only valid thing it can be is a number. + % (We will always have one token, because of the test we just made. + % This is a good thing, since \splitoff doesn't work given nothing at + % all -- the first parameter is undelimited.) + \expandafter\splitoff\thearg\endmark + \ifx\rest\empty + % Only one token in the argument. It could still be anything. + % A ``lowercase letter'' is one whose \lccode is nonzero. + % An ``uppercase letter'' is one whose \lccode is both nonzero, and + % not equal to itself. + % Otherwise, we assume it's a number. + % + % We need the \relax at the end of the \ifnum lines to stop TeX from + % continuing to look for a <number>. + % + \ifnum\lccode\expandafter`\thearg=0\relax + \numericenumerate % a number (we hope) + \else + % It's a letter. + \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax + \lowercaseenumerate % lowercase letter + \else + \uppercaseenumerate % uppercase letter + \fi + \fi + \else + % Multiple tokens in the argument. We hope it's a number. + \numericenumerate + \fi +} + +% An @enumerate whose labels are integers. The starting integer is +% given in \thearg. +% +\def\numericenumerate{% + \itemno = \thearg + \startenumeration{\the\itemno}% +} + +% The starting (lowercase) letter is in \thearg. +\def\lowercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more lowercase letters in @enumerate; get a bigger + alphabet}% + \fi + \char\lccode\itemno + }% +} + +% The starting (uppercase) letter is in \thearg. +\def\uppercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more uppercase letters in @enumerate; get a bigger + alphabet} + \fi + \char\uccode\itemno + }% +} + +% Call \doitemize, adding a period to the first argument and supplying the +% common last two arguments. Also subtract one from the initial value in +% \itemno, since @item increments \itemno. +% +\def\startenumeration#1{% + \advance\itemno by -1 + \doitemize{#1.}\flushcr +} + +% @alphaenumerate and @capsenumerate are abbreviations for giving an arg +% to @enumerate. +% +\def\alphaenumerate{\enumerate{a}} +\def\capsenumerate{\enumerate{A}} +\def\Ealphaenumerate{\Eenumerate} +\def\Ecapsenumerate{\Eenumerate} + + +% @multitable macros +% Amy Hendrickson, 8/18/94, 3/6/96 +% +% @multitable ... @end multitable will make as many columns as desired. +% Contents of each column will wrap at width given in preamble. Width +% can be specified either with sample text given in a template line, +% or in percent of \hsize, the current width of text on page. + +% Table can continue over pages but will only break between lines. + +% To make preamble: +% +% Either define widths of columns in terms of percent of \hsize: +% @multitable @columnfractions .25 .3 .45 +% @item ... +% +% Numbers following @columnfractions are the percent of the total +% current hsize to be used for each column. You may use as many +% columns as desired. + + +% Or use a template: +% @multitable {Column 1 template} {Column 2 template} {Column 3 template} +% @item ... +% using the widest term desired in each column. + +% Each new table line starts with @item, each subsequent new column +% starts with @tab. Empty columns may be produced by supplying @tab's +% with nothing between them for as many times as empty columns are needed, +% ie, @tab@tab@tab will produce two empty columns. + +% @item, @tab do not need to be on their own lines, but it will not hurt +% if they are. + +% Sample multitable: + +% @multitable {Column 1 template} {Column 2 template} {Column 3 template} +% @item first col stuff @tab second col stuff @tab third col +% @item +% first col stuff +% @tab +% second col stuff +% @tab +% third col +% @item first col stuff @tab second col stuff +% @tab Many paragraphs of text may be used in any column. +% +% They will wrap at the width determined by the template. +% @item@tab@tab This will be in third column. +% @end multitable + +% Default dimensions may be reset by user. +% @multitableparskip is vertical space between paragraphs in table. +% @multitableparindent is paragraph indent in table. +% @multitablecolmargin is horizontal space to be left between columns. +% @multitablelinespace is space to leave between table items, baseline +% to baseline. +% 0pt means it depends on current normal line spacing. +% +\newskip\multitableparskip +\newskip\multitableparindent +\newdimen\multitablecolspace +\newskip\multitablelinespace +\multitableparskip=0pt +\multitableparindent=6pt +\multitablecolspace=12pt +\multitablelinespace=0pt + +% Macros used to set up halign preamble: +% +\let\endsetuptable\relax +\def\xendsetuptable{\endsetuptable} +\let\columnfractions\relax +\def\xcolumnfractions{\columnfractions} +\newif\ifsetpercent + +% #1 is the @columnfraction, usually a decimal number like .5, but might +% be just 1. We just use it, whatever it is. +% +\def\pickupwholefraction#1 {% + \global\advance\colcount by 1 + \expandafter\xdef\csname col\the\colcount\endcsname{#1\hsize}% + \setuptable +} + +\newcount\colcount +\def\setuptable#1{% + \def\firstarg{#1}% + \ifx\firstarg\xendsetuptable + \let\go = \relax + \else + \ifx\firstarg\xcolumnfractions + \global\setpercenttrue + \else + \ifsetpercent + \let\go\pickupwholefraction + \else + \global\advance\colcount by 1 + \setbox0=\hbox{#1\unskip\space}% Add a normal word space as a + % separator; typically that is always in the input, anyway. + \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% + \fi + \fi + \ifx\go\pickupwholefraction + % Put the argument back for the \pickupwholefraction call, so + % we'll always have a period there to be parsed. + \def\go{\pickupwholefraction#1}% + \else + \let\go = \setuptable + \fi% + \fi + \go +} + +% multitable-only commands. +% +% @headitem starts a heading row, which we typeset in bold. Assignments +% have to be global since we are inside the implicit group of an +% alignment entry. \everycr below 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 + \gdef\headitemcrhook{\nobreak}% attempt to avoid page break after headings + \global\everytab={\bf}% can't use \headitemfont since the parsing differs + \the\everytab % for the first item +}% +% +% default for tables with no headings. +\let\headitemcrhook=\relax +% +% 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={}% Reset from possible headitem. + \global\colcount=0 % Reset the column counter. + % + % Check for saved footnotes, etc.: + \checkinserts + % + % Perhaps a \nobreak, then reset: + \headitemcrhook + \global\let\headitemcrhook=\relax + }% + }% + % + \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 +} + +% Like \expandablevalue, but completely expandable (the \message in the +% definition above operates at the execution level of TeX). Used when +% writing to auxiliary files, due to the expansion that \write does. +% If flag is undefined, pass through an unexpanded @value command: maybe it +% will be set by the time it is read back in. +% +% NB flag names containing - or _ may not work here. +\def\dummyvalue#1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \noexpand\value{#1}% + \else + \csname SET#1\endcsname + \fi +} + +% Used for @value's in index entries to form the sort key: expand the @value +% if possible, otherwise sort late. +\def\indexnofontsvalue#1{% + \expandafter\ifx\csname SET#1\endcsname\relax + ZZZZZZZ + \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 IX. +% It automatically defines \IXindex such that +% \IXindex ...rest of line... puts an entry in the index IX. +% It also defines \IXindfile to be the number of the output channel for +% the file that accumulates this index. The file's extension is IX. +% The name of an index should be no more than 2 characters long +% for the sake of vms. +% +\def\newindex#1{% + \expandafter\chardef\csname#1indfile\endcsname=0 + \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{% + \expandafter\chardef\csname#1indfile\endcsname=0 + \expandafter\xdef\csname#1index\endcsname{% + \noexpand\docodeindex{#1}}% +} + +% The default indices: +\newindex{cp}% concepts, +\newcodeindex{fn}% functions, +\newcodeindex{vr}% variables, +\newcodeindex{tp}% types, +\newcodeindex{ky}% keys +\newcodeindex{pg}% and programs. + + +% @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{% + \requireopenindexfile{#3}% + % 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 index macros. +% Argument #1 is generated by the calling \fooindex macro, +% and it is the two-letter name of the index. + +\def\doindex#1{\edef\indexname{#1}\parsearg\doindexxxx} +\def\doindexxxx #1{\doind{\indexname}{#1}} + +% like the previous two, but they put @code around the argument. +\def\docodeindex#1{\edef\indexname{#1}\parsearg\docodeindexxxx} +\def\docodeindexxxx #1{\doind{\indexname}{\code{#1}}} + + +% Used when writing an index entry out to an index file to prevent +% expansion of Texinfo commands that can appear in an index entry. +% +\def\indexdummies{% + \escapechar = `\\ % use backslash in output files. + \definedummyletter\@% + \definedummyletter\ % + % + % For texindex which always views { and } as separators. + \def\{{\lbracechar{}}% + \def\}{\rbracechar{}}% + % + % Do the redefinitions. + \definedummies +} + +% Used for the aux and toc files, where @ is the escape character. +% +\def\atdummies{% + \definedummyletter\@% + \definedummyletter\ % + \definedummyletter\{% + \definedummyletter\}% + % + % Do the redefinitions. + \definedummies + \otherbackslash +} + +% \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. +% +% 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). +% +% For control letters, we have \definedummyletter, which omits the +% space. +% +\def\definedummyword #1{\def#1{\string#1\space}}% +\def\definedummyletter#1{\def#1{\string#1}}% +\let\definedummyaccent\definedummyletter + +% Called from \indexdummies and \atdummies, to effectively prevent +% the expansion of commands. +% +\def\definedummies{% + % + \let\commondummyword\definedummyword + \let\commondummyletter\definedummyletter + \let\commondummyaccent\definedummyaccent + \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\atchar + \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\mathopsup + \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\sub + \definedummyword\sup + \definedummyword\textdegree + % + % We want to disable all macros so that they are not expanded by \write. + \macrolist + \let\value\dummyvalue + % + \normalturnoffactive +} + +% \commondummiesnofonts: common to \definedummies and \indexnofonts. +% Define \commondummyletter, \commondummyaccent and \commondummyword before +% using. Used for accents, font commands, and various control letters. +% +\def\commondummiesnofonts{% + % Control letters and accents. + \commondummyletter\!% + \commondummyaccent\"% + \commondummyaccent\'% + \commondummyletter\*% + \commondummyaccent\,% + \commondummyletter\.% + \commondummyletter\/% + \commondummyletter\:% + \commondummyaccent\=% + \commondummyletter\?% + \commondummyaccent\^% + \commondummyaccent\`% + \commondummyaccent\~% + \commondummyword\u + \commondummyword\v + \commondummyword\H + \commondummyword\dotaccent + \commondummyword\ogonek + \commondummyword\ringaccent + \commondummyword\tieaccent + \commondummyword\ubaraccent + \commondummyword\udotaccent + \commondummyword\dotless + % + % Texinfo font commands. + \commondummyword\b + \commondummyword\i + \commondummyword\r + \commondummyword\sansserif + \commondummyword\sc + \commondummyword\slanted + \commondummyword\t + % + % Commands that take arguments. + \commondummyword\abbr + \commondummyword\acronym + \commondummyword\anchor + \commondummyword\cite + \commondummyword\code + \commondummyword\command + \commondummyword\dfn + \commondummyword\dmn + \commondummyword\email + \commondummyword\emph + \commondummyword\env + \commondummyword\file + \commondummyword\image + \commondummyword\indicateurl + \commondummyword\inforef + \commondummyword\kbd + \commondummyword\key + \commondummyword\math + \commondummyword\option + \commondummyword\pxref + \commondummyword\ref + \commondummyword\samp + \commondummyword\strong + \commondummyword\tie + \commondummyword\U + \commondummyword\uref + \commondummyword\url + \commondummyword\var + \commondummyword\verb + \commondummyword\w + \commondummyword\xref +} + +% This does nothing, but for a time it was recommended to use +% \usebracesinindexestrue to be able to use braces in index entries. + +\let\indexlbrace\relax +\let\indexrbrace\relax + +{\catcode`\@=0 +\catcode`\\=13 + @gdef@backslashdisappear{@def\{}} +} + +{ +\catcode`\<=13 +\catcode`\-=13 +\catcode`\`=13 + \gdef\indexnonalnumdisappear{% + \expandafter\ifx\csname SETtxiindexlquoteignore\endcsname\relax\else + % @set txiindexlquoteignore makes us ignore left quotes in the sort term. + % (Introduced for FSFS 2nd ed.) + \let`=\empty + \fi + % + \expandafter\ifx\csname SETtxiindexbackslashignore\endcsname\relax\else + \backslashdisappear + \fi + % + \expandafter\ifx\csname SETtxiindexhyphenignore\endcsname\relax\else + \def-{}% + \fi + \expandafter\ifx\csname SETtxiindexlessthanignore\endcsname\relax\else + \def<{}% + \fi + \expandafter\ifx\csname SETtxiindexatsignignore\endcsname\relax\else + \def\@{}% + \fi + } + + \gdef\indexnonalnumreappear{% + \useindexbackslash + \let-\normaldash + \let<\normalless + \def\@{@}% + } +} + + +% \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\commondummyaccent##1{\let##1\asis}% + % We can just ignore other control letters. + \def\commondummyletter##1{\let##1\empty}% + % All control words become @asis by default; overrides below. + \let\commondummyword\commondummyaccent + \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 + % + \uccode`\1=`\{ \uppercase{\def\{{1}}% + \uccode`\1=`\} \uppercase{\def\}{1}}% + \let\lbracechar\{% + \let\rbracechar\}% + % + % Non-English letters. + \def\AA{AA}% + \def\AE{AE}% + \def\DH{DZZ}% + \def\L{L}% + \def\OE{OE}% + \def\O{O}% + \def\TH{TH}% + \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{th}% + % + \def\LaTeX{LaTeX}% + \def\TeX{TeX}% + % + % Assorted special characters. \defglyph gives the control sequence a + % definition that removes the {} that follows its use. + \defglyph\atchar{@}% + \defglyph\arrow{->}% + \defglyph\bullet{bullet}% + \defglyph\comma{,}% + \defglyph\copyright{copyright}% + \defglyph\dots{...}% + \defglyph\enddots{...}% + \defglyph\equiv{==}% + \defglyph\error{error}% + \defglyph\euro{euro}% + \defglyph\expansion{==>}% + \defglyph\geq{>=}% + \defglyph\guillemetleft{<<}% + \defglyph\guillemetright{>>}% + \defglyph\guilsinglleft{<}% + \defglyph\guilsinglright{>}% + \defglyph\leq{<=}% + \defglyph\lbracechar{\{}% + \defglyph\minus{-}% + \defglyph\point{.}% + \defglyph\pounds{pounds}% + \defglyph\print{-|}% + \defglyph\quotedblbase{"}% + \defglyph\quotedblleft{"}% + \defglyph\quotedblright{"}% + \defglyph\quoteleft{`}% + \defglyph\quoteright{'}% + \defglyph\quotesinglbase{,}% + \defglyph\rbracechar{\}}% + \defglyph\registeredsymbol{R}% + \defglyph\result{=>}% + \defglyph\textdegree{o}% + % + % We need to get rid of all macros, leaving only the arguments (if present). + % Of course this is not nearly correct, but it is the best we can do for now. + % makeinfo does not expand macros in the argument to @deffn, which ends up + % writing an index entry, and texindex isn't prepared for an index sort entry + % that starts with \. + % + % Since macro invocations are followed by braces, we can just redefine them + % to take a single TeX argument. The case of a macro invocation that + % goes to end-of-line is not handled. + % + \macrolist + \let\value\indexnofontsvalue +} +\def\defglyph#1#2{\def#1##1{#2}} % see above + + + + +\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}{}} + +% There is also \dosubind {index}{topic}{subtopic} +% which makes an entry in a two-level index such as the operation index. +% TODO: Two-level index? Operation index? + +% Workhorse for all indexes. +% #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 + {% + \requireopenindexfile{#1}% + % 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 +} + +% Check if an index file has been opened, and if not, open it. +\def\requireopenindexfile#1{% +\ifnum\csname #1indfile\endcsname=0 + \expandafter\newwrite \csname#1indfile\endcsname + \edef\suffix{#1}% + % A .fls suffix would conflict with the file extension for the output + % of -recorder, so use .f1s instead. + \ifx\suffix\indexisfl\def\suffix{f1}\fi + % Open the file + \immediate\openout\csname#1indfile\endcsname \jobname.\suffix + % Using \immediate above here prevents an object entering into the current + % box, which could confound checks such as those in \safewhatsit for + % preceding skips. + \typeout{Writing index file \jobname.\suffix}% +\fi} +\def\indexisfl{fl} + +% Output \ as {\indexbackslash}, because \ is an escape character in +% the index files. +\let\indexbackslash=\relax +{\catcode`\@=0 \catcode`\\=\active + @gdef@useindexbackslash{@def\{{@indexbackslash}}} +} + +% Definition for writing index entry text. +\def\sortas#1{\ignorespaces}% + +% Definition for writing index entry sort key. Should occur at the at +% the beginning of the index entry, like +% @cindex @sortas{september} \september +% The \ignorespaces takes care of following space, but there's no way +% to remove space before it. +{ +\catcode`\-=13 +\gdef\indexwritesortas{% + \begingroup + \indexnonalnumreappear + \indexwritesortasxxx} +\gdef\indexwritesortasxxx#1{% + \xdef\indexsortkey{#1}\endgroup} +} + + +% 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 + \useindexbackslash % \indexbackslash isn't defined now so it will be output + % as is; and it will print as backslash. + % The braces around \indexbrace are recognized by texindex. + % + % Get the string to sort by, by processing the index entry with all + % font commands turned off. + {\indexnofonts + \def\lbracechar{{\indexlbrace}}% + \def\rbracechar{{\indexrbrace}}% + \let\{=\lbracechar + \let\}=\rbracechar + \indexnonalnumdisappear + \xdef\indexsortkey{}% + \let\sortas=\indexwritesortas + \edef\temp{\the\toks0}% + \setbox\dummybox = \hbox{\temp}% Make sure to execute any \sortas + \ifx\indexsortkey\empty + \xdef\indexsortkey{\temp}% + \ifx\indexsortkey\empty\xdef\indexsortkey{ }\fi + \fi + }% + % + % 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{\indexsortkey}{\noexpand\folio}{\the\toks0}}% + }% + \temp +} +\newbox\dummybox % used above + +% 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`\@ = 12 + % See comment in \requireopenindexfile. + \def\indexname{#1}\ifx\indexname\indexisfl\def\indexname{f1}\fi + \openin 1 \jobname.\indexname s + \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 + \typeout{No file \jobname.\indexname s.}% + \else + \catcode`\\ = 0 + % + % 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 \thisline + \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{\ttbackslash}% + \let\indexlbrace\{ % Likewise, set these sequences for braces + \let\indexrbrace\} % used in the sort key. + \begindoublecolumns + \let\dotheinsertentrybox\dotheinsertentryboxwithpenalty + % + % Read input from the index file line by line. + \loopdo + \ifeof1 \else + \read 1 to \nextline + \fi + % + \indexinputprocessing + \thisline + % + \ifeof1\else + \let\thisline\nextline + \repeat + %% + \enddoublecolumns + \fi + \fi + \closein 1 +\endgroup} +\def\loopdo#1\repeat{\def\body{#1}\loopdoxxx} +\def\loopdoxxx{\let\next=\relax\body\let\next=\loopdoxxx\fi\next} + +\def\indexinputprocessing{% + \ifeof1 + \let\firsttoken\relax + \else + \edef\act{\gdef\noexpand\firsttoken{\getfirsttoken\nextline}}% + \act + \fi +} +\def\getfirsttoken#1{\expandafter\getfirsttokenx#1\endfirsttoken} +\long\def\getfirsttokenx#1#2\endfirsttoken{\noexpand#1} + + +% These macros are used by the sorted index file itself. +% Change them to control the appearance of the index. + +{\catcode`\/=13 \catcode`\-=13 \catcode`\^=13 \catcode`\~=13 \catcode`\_=13 +\catcode`\|=13 \catcode`\<=13 \catcode`\>=13 \catcode`\+=13 \catcode`\"=13 +\catcode`\$=3 +\gdef\initialglyphs{% + % Some changes for non-alphabetic characters. Using the glyphs from the + % math fonts looks more consistent than the typewriter font used elsewhere + % for these characters. + \def\indexbackslash{\math{\backslash}}% + \let\\=\indexbackslash + % + % Can't get bold backslash so don't use bold forward slash + \catcode`\/=13 + \def/{{\secrmnotbold \normalslash}}% + \def-{{\normaldash\normaldash}}% en dash `--' + \def^{{\chapbf \normalcaret}}% + \def~{{\chapbf \normaltilde}}% + \def\_{% + \leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em }% + \def|{$\vert$}% + \def<{$\less$}% + \def>{$\gtr$}% + \def+{$\normalplus$}% +}} + +\def\initial{% + \bgroup + \initialglyphs + \initialx +} + +\def\initialx#1{% + % Remove any glue we may have, we'll be inserting our own. + \removelastskip + % + % We like breaks before the index initials, so insert a bonus. + % The glue before the bonus allows a little bit of space at the + % bottom of a column to reduce an increase in inter-line spacing. + \nobreak + \vskip 0pt plus 5\baselineskip + \penalty -300 + \vskip 0pt plus -5\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 1\baselineskip + \leftline{\secfonts \kern-0.05em \secbf #1}% + % \secfonts is inside the argument of \leftline so that the change of + % \baselineskip will not affect any glue inserted before the vbox that + % \leftline creates. + % Do our best not to break after the initial. + \nobreak + \vskip .33\baselineskip plus .1\baselineskip + \egroup % \initialglyphs +} + +\newdimen\entryrightmargin +\entryrightmargin=0pt + +% \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. +% +\def\entry{% + \begingroup + % + % For pdfTeX and XeTeX. + % The redefinition of \domark stops marks being added in \pdflink to + % preserve coloured links across page boundaries. Otherwise the marks + % would get in the way of \lastbox in \insertentrybox. + \let\domark\relax + % + % Start a new paragraph if necessary, so our assignments below can't + % affect previous text. + \par + % + % No extra space above this paragraph. + \parskip = 0in + % + % 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}% An undocumented command + % + % Swallow the left brace of the text (first parameter): + \afterassignment\doentry + \let\temp = +} +\def\entrybreak{\unskip\space\ignorespaces}% +\def\doentry{% + % Save the text of the entry + \global\setbox\boxA=\hbox\bgroup + \bgroup % Instead of the swallowed brace. + \noindent + \aftergroup\finishentry + % And now comes the text of the entry. + % Not absorbing as a macro argument reduces the chance of problems + % with catcodes occurring. +} +{\catcode`\@=11 +\gdef\finishentry#1{% + \egroup % end box A + \dimen@ = \wd\boxA % Length of text of entry + \global\setbox\boxA=\hbox\bgroup\unhbox\boxA + % #1 is the page number. + % + % Get the width of the page numbers, and only use + % leaders if they are present. + \global\setbox\boxB = \hbox{#1}% + \ifdim\wd\boxB = 0pt + \null\nobreak\hfill\ % + \else + % + \null\nobreak\indexdotfill % Have leaders before the page number. + % + \ifpdf + \pdfgettoks#1.% + \hskip\skip\thinshrinkable\the\toksA + \else + \ifx\XeTeXrevision\thisisundefined + \hskip\skip\thinshrinkable #1% + \else + \pdfgettoks#1.% + \hskip\skip\thinshrinkable\the\toksA + \fi + \fi + \fi + \egroup % end \boxA + \ifdim\wd\boxB = 0pt + \global\setbox\entrybox=\vbox{\unhbox\boxA}% + \else + \global\setbox\entrybox=\vbox\bgroup + % We want the text of the entries to be aligned to the left, and the + % page numbers to be aligned to the right. + % + \parindent = 0pt + \advance\leftskip by 0pt plus 1fil + \advance\leftskip by 0pt plus -1fill + \rightskip = 0pt plus -1fil + \advance\rightskip by 0pt plus 1fill + % Cause last line, which could consist of page numbers on their own + % if the list of page numbers is long, to be aligned to the right. + \parfillskip=0pt plus -1fill + % + \advance\rightskip by \entryrightmargin + % Determine how far we can stretch into the margin. + % This allows, e.g., "Appendix H GNU Free Documentation License" to + % fit on one line in @letterpaper format. + \ifdim\entryrightmargin>2.1em + \dimen@i=2.1em + \else + \dimen@i=0em + \fi + \advance \parfillskip by 0pt minus 1\dimen@i + % + \dimen@ii = \hsize + \advance\dimen@ii by -1\leftskip + \advance\dimen@ii by -1\entryrightmargin + \advance\dimen@ii by 1\dimen@i + \ifdim\wd\boxA > \dimen@ii % If the entry doesn't fit in one line + \ifdim\dimen@ > 0.8\dimen@ii % due to long index text + % Try to split the text roughly evenly. \dimen@ will be the length of + % the first line. + \dimen@ = 0.7\dimen@ + \dimen@ii = \hsize + \ifnum\dimen@>\dimen@ii + % If the entry is too long (for example, if it needs more than + % two lines), use all the space in the first line. + \dimen@ = \dimen@ii + \fi + \advance\leftskip by 0pt plus 1fill % ragged right + \advance \dimen@ by 1\rightskip + \parshape = 2 0pt \dimen@ 0em \dimen@ii + % Ideally we'd add a finite glue at the end of the first line only, + % instead of using \parshape with explicit line lengths, but TeX + % doesn't seem to provide a way to do such a thing. + % + % Indent all lines but the first one. + \advance\leftskip by 1em + \advance\parindent by -1em + \fi\fi + \indent % start paragraph + \unhbox\boxA + % + % Do not prefer a separate line ending with a hyphen to fewer lines. + \finalhyphendemerits = 0 + % + % Word spacing - no stretch + \spaceskip=\fontdimen2\font minus \fontdimen4\font + % + \linepenalty=1000 % Discourage line breaks. + \hyphenpenalty=5000 % Discourage hyphenation. + % + \par % format the paragraph + \egroup % The \vbox + \fi + \endgroup + \dotheinsertentrybox +}} + +\newskip\thinshrinkable +\skip\thinshrinkable=.15em minus .15em + +\newbox\entrybox +\def\insertentrybox{% + \ourunvbox\entrybox +} + +% default definition +\let\dotheinsertentrybox\insertentrybox + +% Use \lastbox to take apart vbox box by box, and add each sub-box +% to the current vertical list. +\def\ourunvbox#1{% +\bgroup % for local binding of \delayedbox + % Remove the last box from box #1 + \global\setbox#1=\vbox{% + \unvbox#1% + \unskip % remove any glue + \unpenalty + \global\setbox\interbox=\lastbox + }% + \setbox\delayedbox=\box\interbox + \ifdim\ht#1=0pt\else + \ourunvbox#1 % Repeat on what's left of the box + \nobreak + \fi + \box\delayedbox +\egroup +} +\newbox\delayedbox +\newbox\interbox + +% Used from \printindex. \firsttoken should be the first token +% after the \entry. If it's not another \entry, we are at the last +% line of a group of index entries, so insert a penalty to discourage +% widowed index entries. +\def\dotheinsertentryboxwithpenalty{% + \ifx\firsttoken\isentry + \else + \penalty 9000 + \fi + \insertentrybox +} +\def\isentry{\entry}% + +% Like plain.tex's \dotfill, except uses up at least 1 em. +% The filll stretch here overpowers both the fil and fill stretch to push +% the page number to the right. +\def\indexdotfill{\cleaders + \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1filll} + + +\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 + \ifx\XeTeXrevision\thisisundefined + #2 + \else + \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph. + \fi + \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 % private names + +\newbox\partialpage +\newdimen\doublecolumnhsize + +% Use inside an output routine to save \topmark and \firstmark +\def\savemarks{% + \global\savedtopmark=\expandafter{\topmark }% + \global\savedfirstmark=\expandafter{\firstmark }% +} +\newtoks\savedtopmark +\newtoks\savedfirstmark + +% Set \topmark and \firstmark for next time \output runs. +% Can't be run from withinside \output (because any material +% added while an output routine is active, including +% penalties, is saved for after it finishes). The page so far +% should be empty, otherwise what's on it will be thrown away. +\def\restoremarks{% + \mark{\the\savedtopmark}% + \bgroup\output = {% + \setbox\dummybox=\box\PAGE + }abc\eject\egroup + % "abc" because output routine doesn't fire for a completely empty page. + \mark{\the\savedfirstmark}% +} + +\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns + % If not much space left on page, start a new page. + \ifdim\pagetotal>0.8\vsize\vfill\eject\fi + % + % 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 + }% + \savemarks + }% + \eject % run that output routine to set \partialpage + \restoremarks + % + % We recover the two marks that the last output routine saved in order + % to propagate the information in marks added around a chapter heading, + % which could be otherwise be lost by the time the final page is output. + % + % + % 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 + % + % Get the available space for the double columns -- the normal + % (undoubled) page height minus any material left over from the + % previous page. + \advance\vsize by -\ht\partialpage + \vsize = 2\vsize + % + % For the benefit of balancing columns + \advance\baselineskip by 0pt plus 0.5pt +} + +% The double-column output routine for all double-column pages except +% the last, which is done by \balancecolumns. +% +\def\doublecolumnout{% + % + \splittopskip=\topskip \splitmaxdepth=\maxdepth + \dimen@ = \vsize + \divide\dimen@ by 2 + % + % box0 will be the left-hand column, box2 the right. + \setbox0=\vsplit\PAGE to\dimen@ \setbox2=\vsplit\PAGE to\dimen@ + \global\advance\vsize by 2\ht\partialpage + \onepageout\pagesofar % empty except for the first time we are called + \unvbox\PAGE + \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\txipagewidth{\box0\hfil\box2}% +} + + +% Finished with 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 \txipageheight (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. + \savemarks + \balancecolumns + }% + \eject % call the \output just set + \ifdim\pagetotal=0pt + % Having called \balancecolumns once, we do not + % want to call it again. Therefore, reset \output to its normal + % definition right away. + \global\output = {\onepageout{\pagecontents\PAGE}}% + % + \endgroup % started in \begindoublecolumns + \restoremarks + % Leave the double-column material on the current page, no automatic + % page break. + \box\balancedcolumns + % + % \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. + \global\vsize = \txipageheight % + \pagegoal = \txipageheight % + \else + % We had some left-over material. This might happen when \doublecolumnout + % is called in \balancecolumns. Try again. + \expandafter\enddoublecolumns + \fi +} +\newbox\balancedcolumns +\setbox\balancedcolumns=\vbox{shouldnt see this}% +% +% Only called for the last of the double column material. \doublecolumnout +% does the others. +\def\balancecolumns{% + \setbox0 = \vbox{\unvbox\PAGE}% like \box255 but more efficient, see p.120. + \dimen@ = \ht0 + \ifdim\dimen@<7\baselineskip + % Don't split a short final column in two. + \setbox2=\vbox{}% + \global\setbox\balancedcolumns=\vbox{\pagesofar}% + \else + % double the leading vertical space + \advance\dimen@ by \topskip + \advance\dimen@ by-\baselineskip + \divide\dimen@ by 2 % target to split to + \dimen@ii = \dimen@ + \splittopskip = \topskip + % Loop until left column is at least as high as the right column. + {% + \vbadness = 10000 + \loop + \global\setbox3 = \copy0 + \global\setbox1 = \vsplit3 to \dimen@ + \ifdim\ht1<\ht3 + \global\advance\dimen@ by 1pt + \repeat + }% + % Now the left column is in box 1, and the right column in box 3. + % + % Check whether the left column has come out higher than the page itself. + % (Note that we have doubled \vsize for the double columns, so + % the actual height of the page is 0.5\vsize). + \ifdim2\ht1>\vsize + % It appears that we have been called upon to balance too much material. + % Output some of it with \doublecolumnout, leaving the rest on the page. + \setbox\PAGE=\box0 + \doublecolumnout + \else + % Compare the heights of the two columns. + \ifdim4\ht1>5\ht3 + % Column heights are too different, so don't make their bottoms + % flush with each other. + \setbox2=\vbox to \ht1 {\unvbox3\vfill}% + \setbox0=\vbox to \ht1 {\unvbox1\vfill}% + \else + % Make column bottoms flush with each other. + \setbox2=\vbox to\ht1{\unvbox3\unskip}% + \setbox0=\vbox to\ht1{\unvbox1\unskip}% + \fi + \global\setbox\balancedcolumns=\vbox{\pagesofar}% + \fi + \fi + % +} +\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\rm #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 + % This outputs a mark at the end of the page that clears \thischapter + % and \thissection, as is done in \startcontents. + \let\pchapsepmacro\relax + \chapmacro{}{Yomitfromtoc}{}% + \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<toks register> to achieve this: TeX expands \the<toks> only once, + % simply yielding the contents of <toks register>. (We also do this for + % the toc entries.) + \toks0 = {#1}% + \message{(\the\toks0)}% + % + \chapmacro{#1}{Ynothing}{\the\unnumberedno}% + % + \global\let\section = \unnumberedsec + \global\let\subsection = \unnumberedsubsec + \global\let\subsubsection = \unnumberedsubsubsec +} + +% @centerchap is like @unnumbered, but the heading is centered. +\outer\parseargdef\centerchap{% + \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}} + +% Start a new page +\def\chappager{\par\vfill\supereject} + +% \chapoddpage - start on an odd page for a new chapter +% 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 +} + +\parseargdef\setchapternewpage{\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 + +% \chapmacro - Chapter opening. +% +% #1 is the text, #2 is the section type (Ynumbered, Ynothing, +% Yappendix, Yomitfromtoc), #3 the chapter number. +% Not used for @heading series. +% +% To test against our argument. +\def\Ynothingkeyword{Ynothing} +\def\Yappendixkeyword{Yappendix} +\def\Yomitfromtockeyword{Yomitfromtoc} +% +\def\chapmacro#1#2#3{% + \expandafter\ifx\thisenv\titlepage\else + \checkenv{}% chapters, etc., should not start inside an environment. + \fi + % FIXME: \chapmacro is currently called from inside \titlepage when + % \setcontentsaftertitlepage to print the "Table of Contents" heading, but + % this should probably be done by \sectionheading with an option to print + % in chapter size. + % + % 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 \rm + \let\footnote=\errfootnoteheading % give better error message + % + % 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 +} + + +% 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 of the title, +% #2 is the section level (sec/subsec/subsubsec), +% #3 is the section type (Ynumbered, Ynothing, Yappendix, Yomitfromtoc), +% #4 is the section number. +% +\def\seckeyword{sec} +% +\def\sectionheading#1#2#3#4{% + {% + \def\sectionlevel{#2}% + \def\temptype{#3}% + % + % It is ok for the @heading series commands to appear inside an + % environment (it's been historically allowed, though the logic is + % dubious), but not the others. + \ifx\temptype\Yomitfromtockeyword\else + \checkenv{}% non-@*heading should not be in an environment. + \fi + \let\footnote=\errfootnoteheading + % + % Switch to the right set of fonts. + \csname #2fonts\endcsname \rm + % + % 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 + \else + \ifx\XeTeXrevision\thisisundefined + \else + \global\pdfmakepagedesttrue + \fi + \fi +} + + +% These characters do not print properly in the Computer Modern roman +% fonts, so we must take special care. This is more or less redundant +% with the Texinfo input format setup at the end of this file. +% +\def\activecatcodes{% + \catcode`\"=\active + \catcode`\$=\active + \catcode`\<=\active + \catcode`\>=\active + \catcode`\\=\active + \catcode`\^=\active + \catcode`\_=\active + \catcode`\|=\active + \catcode`\~=\active +} + + +% Read the toc file, which is essentially Texinfo input. +\def\readtocfile{% + \setupdatafile + \activecatcodes + \input \tocreadfilename +} + +\newskip\contentsrightmargin \contentsrightmargin=1in +\newcount\savepageno +\newcount\lastnegativepageno \lastnegativepageno = -1 + +% Prepare to read what we've written to \tocfile. +% +\def\startcontents#1{% + % If @setchapternewpage on, and @headings double, the contents should + % start on an odd page, unlike chapters. Thus, we maintain + % \contentsalignmacro in parallel with \pagealignmacro. + % From: Torbjorn Granlund <tege@matematik.su.se> + \contentsalignmacro + \immediate\closeout\tocfile + % + % Don't need to put `Contents' or `Short Contents' in the headline. + % It is abundantly clear what they are. + \chapmacro{#1}{Yomitfromtoc}{}% + % + \savepageno = \pageno + \begingroup % Set up to handle contents files properly. + \raggedbottom % Worry more about breakpoints than the bottom. + \entryrightmargin=\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{% + % Add stretch and a bonus for breaking the page before the part heading. + % This reduces the chance of the page being broken immediately after the + % part heading, before a following chapter heading. + \vskip 0pt plus 5\baselineskip + \penalty-300 + \vskip 0pt plus -5\baselineskip + \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}\hskip.7em#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 + % Move the page numbers slightly to the right + \advance\entryrightmargin by -0.05em + \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 + % + % ' 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 + % + % Inverse of the list at the beginning of the file. + \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\sp=\ptexsp + \let\*=\ptexstar + %\let\sup=\ptexsup % do not redefine, we want @sup to work in math mode + \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 + \ifnum\lastpenalty<10000 + % Penalize breaking before the environment, because preceding text + % often leads into it. + \penalty100 + \fi + \vskip\envskipamount + \fi + \fi +}} + +\def\afterenvbreak{{% + % =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 +}} + +% \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 + % + % 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 + % + \setbox\groupbox=\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 + \addgroupbox + \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. Don't stretch around special +% characters in urls in this environment, since the stretch at the right +% should be enough. +\envdef\raggedright{% + \rightskip0pt plus2.4em \spaceskip.3333em \xspaceskip.5em\relax + \def\urefprestretchamount{0pt}% + \def\urefpoststretchamount{0pt}% +} +\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{<char>...<char>} +% If we want to allow any <char> as delimiter, +% we need the curly braces so that makeinfo sees the @verb command, eg: +% `@verbx...x' would look like the '@verbx' command. --janneke@gnu.org +% +% [Knuth]: Donald Ervin Knuth, 1996. The TeXbook. +% +% [Knuth] p.344; only we need to do the other characters Texinfo sets +% active too. Otherwise, they get lost as the first character on a +% verbatim line. +\def\dospecials{% + \do\ \do\\\do\{\do\}\do\$\do\&% + \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~% + \do\<\do\>\do\|\do\@\do+\do\"% + % 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 \starttabbox 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'{'<char>#1<char>'}'{#1} +% +% [Knuth] p. 382; only eat outer {} +\begingroup + \catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other + \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next] +\endgroup +% +\def\verb{\begingroup\setupverb\doverb} +% +% +% Do the @verbatim magic: define the macro \doverbatim so that +% the (first) argument ends when '@end verbatim' is reached, ie: +% +% \def\doverbatim#1@end verbatim{#1} +% +% For Texinfo it's a lot easier than for LaTeX, +% because texinfo's \verbatim doesn't stop at '\end{verbatim}': +% we need not redefine '\', '{' and '}'. +% +% Inspired by LaTeX's verbatim command set [latex.ltx] +% +\begingroup + \catcode`\ =\active + \obeylines % + % ignore everything up to the first ^^M, that's the newline at the end + % of the @verbatim input line itself. Otherwise we get an extra blank + % line in the output. + \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}% + % We really want {...\end verbatim} in the body of the macro, but + % without the active space; thus we have to use \xdef and \gobble. +\endgroup +% +\envdef\verbatim{% + \setupverbatim\doverbatim +} +\let\Everbatim = \afterenvbreak + + +% @verbatiminclude FILE - insert text of file in verbatim environment. +% +\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude} +% +\def\doverbatiminclude#1{% + {% + \makevalueexpandable + \setupverbatim + {% + \indexnofonts % Allow `@@' and other weird things in file names. + \wlog{texinfo.tex: doing @verbatiminclude of #1^^J}% + \edef\tmp{\noexpand\input #1 } + \expandafter + }\tmp + \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 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 { (defn. of \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 \rmfont + % + \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} +} +\let\ampchar\& + +\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 + +% alias because \c means cedilla in @tex or @math +\let\texinfoc=\c + +\newcount\savedcatcodeone +\newcount\savedcatcodetwo + +% Used at the time of macro expansion. +% Argument is macro body with arguments substituted +\def\scanmacro#1{% + \newlinechar`\^^M + \def\xeatspaces{\eatspaces}% + % + % Temporarily undo catcode changes of \printindex. Set catcode of @ to + % 0 so that @-commands in macro expansions aren't printed literally when + % formatting an index file, where \ is used as the escape character. + \savedcatcodeone=\catcode`\@ + \savedcatcodetwo=\catcode`\\ + \catcode`\@=0 + \catcode`\\=\active + % + % Process the macro body under the current catcode regime. + \scantokens{#1@texinfoc}% + % + \catcode`\@=\savedcatcodeone + \catcode`\\=\savedcatcodetwo + % + % The \texinfoc is to remove the \newlinechar added by \scantokens, and + % can be noticed by \parsearg. + % We avoid surrounding the call to \scantokens with \bgroup and \egroup + % to allow macros to open or close groups themselves. +} + +% Used for copying and captions +\def\scanexp#1{% + \expandafter\scanmacro\expandafter{#1}% +} + +\newcount\paramno % Count of parameters +\newtoks\macname % Macro name +\newif\ifrecursive % Is it recursive? + +% List of all defined macros in the form +% \commondummyword\macro1\commondummyword\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\commondummyword#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 + \passthroughcharstrue +} + +\def\scanargctxt{% used for copying and captions, not macros. + \scanctxt + \catcode`\@=\other + \catcode`\\=\other + \catcode`\^^M=\other +} + +\def\macrobodyctxt{% used for @macro definitions + \scanctxt + \catcode`\ =\other + \catcode`\@=\other + \catcode`\{=\other + \catcode`\}=\other + \catcode`\^^M=\other + \usembodybackslash +} + +% Used when scanning braced macro arguments. Note, however, that catcode +% changes here are ineffectual if the macro invocation was nested inside +% an argument to another Texinfo command. +\def\macroargctxt{% + \scanctxt + \catcode`\ =\active + \catcode`\^^M=\other + \catcode`\\=\active +} + +\def\macrolineargctxt{% used for whole-line arguments without braces + \scanctxt + \catcode`\{=\other + \catcode`\}=\other +} + +% \mbodybackslash is the definition of \ in @macro bodies. +% It maps \foo\ => \csname macarg.foo\endcsname => #N +% where N is the macro parameter number. +% We define \csname macarg.\endcsname to be \realbackslash, so +% \\ in macro replacement text gets you a backslash. +% +{\catcode`@=0 @catcode`@\=@active + @gdef@usembodybackslash{@let\=@mbodybackslash} + @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname} +} +\expandafter\def\csname macarg.\endcsname{\realbackslash} + +\def\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\commondummyword\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\commondummyword \noexpand#1% + \fi +} + +% \getargs -- Parse the arguments to a @macro line. Set \macname to +% the name of the macro, and \argl to the braced argument list. +\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}} +% This made use of the feature that if the last token of a +% <parameter list> is #, then the preceding argument is delimited by +% an opening brace, and that opening brace is not consumed. + +% Parse the optional {params} list to @macro or @rmacro. +% Set \paramno to the number of arguments, +% and \paramlist to a parameter text for the macro (e.g. #1,#2,#3 for a +% three-param macro.) Define \macarg.BLAH for each BLAH in the params +% list to some hook where the argument is 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). +% +% If there are 10 or more arguments, a different technique is used: see +% \parsemmanyargdef. +% +\def\parsemargdef#1;{% + \paramno=0\def\paramlist{}% + \let\hash\relax + % \hash is redefined to `#' later to get it into definitions + \let\xeatspaces\relax + \parsemargdefxxx#1,;,% + \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} + +% \parsemacbody, \parsermacbody +% +% Read recursive and nonrecursive macro bodies. (They're different since +% rec and nonrec macros end differently.) +% +% We are in \macrobodyctxt, and the \xdef causes backslashshes in the macro +% body to be transformed. +% Set \macrobody to the body of the macro, and call \defmacro. +% +{\catcode`\ =\other\long\gdef\parsemacbody#1@end macro{% +\xdef\macrobody{\eatcr{#1}}\endgroup\defmacro}}% +{\catcode`\ =\other\long\gdef\parsermacbody#1@end rmacro{% +\xdef\macrobody{\eatcr{#1}}\endgroup\defmacro}}% + +% Make @ a letter, so that we can make private-to-Texinfo macro names. +\edef\texiatcatcode{\the\catcode`\@} +\catcode `@=11\relax + +%%%%%%%%%%%%%% Code for > 10 arguments only %%%%%%%%%%%%%%%%%% + +% 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 under which the body was input). +% +% If you compile with TeX (not eTeX), and you have macros with 10 or more +% arguments, no macro can have more than 256 arguments (else error). +% +% 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. +\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} + + +\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}% + } + +% Define the named-macro outside of this group and then close this group. +% +\def\macargexpandinbody@{% + \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 +} + +% Trailing 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}% +} + + +%%%%%%%%%%%%%% End of code for > 10 arguments %%%%%%%%%%%%%%%%%% + + +% This defines a Texinfo @macro or @rmacro, called by \parsemacbody. +% \macrobody has the body of the macro in it, with placeholders for +% its parameters, looking like "\xeatspaces{\hash 1}". +% \paramno is the number of parameters +% \paramlist is a TeX parameter text, e.g. "#1,#2,#3," +% There are four cases: macros of zero, one, up to nine, and many arguments. +% \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 + \ifnum\paramno=1 + \def\xeatspaces##1{##1}% + % This removes the pair of braces around the argument. We don't + % use \eatspaces, because this can cause ends of lines to be lost + % when the argument to \eatspaces is read, leading to line-based + % commands like "@itemize" not being read correctly. + \else + \let\xeatspaces\relax % suppress expansion + \fi + \ifcase\paramno + % 0 + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup + \noexpand\spaceisspace + \noexpand\endlineisspace + \noexpand\expandafter % skip any whitespace after the macro name. + \expandafter\noexpand\csname\the\macname @@@\endcsname}% + \expandafter\xdef\csname\the\macname @@@\endcsname{% + \egroup + \noexpand\scanmacro{\macrobody}}% + \or % 1 + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup + \noexpand\braceorline + \expandafter\noexpand\csname\the\macname @@@\endcsname}% + \expandafter\xdef\csname\the\macname @@@\endcsname##1{% + \egroup + \noexpand\scanmacro{\macrobody}% + }% + \else % at most 9 + \ifnum\paramno<10\relax + % @MACNAME sets the context for reading the macro argument + % @MACNAME@@ gets the argument, processes backslashes and appends a + % comma. + % @MACNAME@@@ removes braces surrounding the argument list. + % @MACNAME@@@@ scans the macro body with arguments substituted. + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup + \noexpand\expandafter % This \expandafter skip any spaces after the + \noexpand\macroargctxt % macro before we change the catcode of space. + \noexpand\expandafter + \expandafter\noexpand\csname\the\macname @@\endcsname}% + \expandafter\xdef\csname\the\macname @@\endcsname##1{% + \noexpand\passargtomacro + \expandafter\noexpand\csname\the\macname @@@\endcsname{##1,}}% + \expandafter\xdef\csname\the\macname @@@\endcsname##1{% + \expandafter\noexpand\csname\the\macname @@@@\endcsname ##1}% + \expandafter\expandafter + \expandafter\xdef + \expandafter\expandafter + \csname\the\macname @@@@\endcsname\paramlist{% + \egroup\noexpand\scanmacro{\macrobody}}% + \else % 10 or more: + \expandafter\xdef\csname\the\macname\endcsname{% + \noexpand\getargvals@{\the\macname}{\argl}% + }% + \global\expandafter\let\csname mac.\the\macname .body\endcsname\macrobody + \global\expandafter\let\csname mac.\the\macname .recurse\endcsname\gobble + \fi + \fi} + +\catcode `\@\texiatcatcode\relax % end private-to-Texinfo catcodes + +\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +{\catcode`\@=0 \catcode`\\=13 % We need to manipulate \ so use @ as escape +@catcode`@_=11 % private names +@catcode`@!=11 % used as argument separator + +% \passargtomacro#1#2 - +% Call #1 with a list of tokens #2, with any doubled backslashes in #2 +% compressed to one. +% +% This implementation works by expansion, and not execution (so we cannot use +% \def or similar). This reduces the risk of this failing in contexts where +% complete expansion is done with no execution (for example, in writing out to +% an auxiliary file for an index entry). +% +% State is kept in the input stream: the argument passed to +% @look_ahead, @gobble_and_check_finish and @add_segment is +% +% THE_MACRO ARG_RESULT ! {PENDING_BS} NEXT_TOKEN (... rest of input) +% +% where: +% THE_MACRO - name of the macro we want to call +% ARG_RESULT - argument list we build to pass to that macro +% PENDING_BS - either a backslash or nothing +% NEXT_TOKEN - used to look ahead in the input stream to see what's coming next + +@gdef@passargtomacro#1#2{% + @add_segment #1!{}@relax#2\@_finish\% +} +@gdef@_finish{@_finishx} @global@let@_finishx@relax + +% #1 - THE_MACRO ARG_RESULT +% #2 - PENDING_BS +% #3 - NEXT_TOKEN +% #4 used to look ahead +% +% If the next token is not a backslash, process the rest of the argument; +% otherwise, remove the next token. +@gdef@look_ahead#1!#2#3#4{% + @ifx#4\% + @expandafter@gobble_and_check_finish + @else + @expandafter@add_segment + @fi#1!{#2}#4#4% +} + +% #1 - THE_MACRO ARG_RESULT +% #2 - PENDING_BS +% #3 - NEXT_TOKEN +% #4 should be a backslash, which is gobbled. +% #5 looks ahead +% +% Double backslash found. Add a single backslash, and look ahead. +@gdef@gobble_and_check_finish#1!#2#3#4#5{% + @add_segment#1\!{}#5#5% +} + +@gdef@is_fi{@fi} + +% #1 - THE_MACRO ARG_RESULT +% #2 - PENDING_BS +% #3 - NEXT_TOKEN +% #4 is input stream until next backslash +% +% Input stream is either at the start of the argument, or just after a +% backslash sequence, either a lone backslash, or a doubled backslash. +% NEXT_TOKEN contains the first token in the input stream: if it is \finish, +% finish; otherwise, append to ARG_RESULT the segment of the argument up until +% the next backslash. PENDING_BACKSLASH contains a backslash to represent +% a backslash just before the start of the input stream that has not been +% added to ARG_RESULT. +@gdef@add_segment#1!#2#3#4\{% +@ifx#3@_finish + @call_the_macro#1!% +@else + % append the pending backslash to the result, followed by the next segment + @expandafter@is_fi@look_ahead#1#2#4!{\}@fi + % this @fi is discarded by @look_ahead. + % we can't get rid of it with \expandafter because we don't know how + % long #4 is. +} + +% #1 - THE_MACRO +% #2 - ARG_RESULT +% #3 discards the res of the conditional in @add_segment, and @is_fi ends the +% conditional. +@gdef@call_the_macro#1#2!#3@fi{@is_fi #1{#2}} + +} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% \braceorline MAC is used for a one-argument macro MAC. It checks +% whether the next non-whitespace character is a {. It sets the context +% for reading the argument (slightly different in the two cases). Then, +% to read the argument, in the whole-line case, it then calls the regular +% \parsearg MAC; in the lbrace case, it calls \passargtomacro MAC. +% +\def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx} +\def\braceorlinexxx{% + \ifx\nchar\bgroup + \macroargctxt + \expandafter\passargtomacro + \else + \macrolineargctxt\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 + {% + \requireauxfile + \atdummies % preserve commands, but don't expand them + % match definition in \xrdef, \refx, \xrefX. + \def\value##1{##1}% + \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{\putwordsee{} \xrefXX} +\def\xref{\putwordSee{} \xrefXX} +\def\ref{\xrefXX} + +\def\xrefXX#1{\def\xrefXXarg{#1}\futurelet\tokenafterxref\xrefXXX} +\def\xrefXXX{\expandafter\xrefX\expandafter[\xrefXXarg,,,,,,,]} +% +\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 + % For pdfTeX and LuaTeX + {\indexnofonts + \makevalueexpandable + \turnoffactive + % 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. + \setpdfdestname{#1}% + % + \ifx\pdfdestname\empty + \def\pdfdestname{Top}% no empty targets + \fi + % + \leavevmode + \startlink attr{/Border [0 0 0]}% + \ifnum\filenamelength>0 + goto file{\the\filename.pdf} name{\pdfdestname}% + \else + goto name{\pdfmkpgn{\pdfdestname}}% + \fi + }% + \setcolor{\linkcolor}% + \else + \ifx\XeTeXrevision\thisisundefined + \else + % For XeTeX + {\indexnofonts + \makevalueexpandable + \turnoffactive + % 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. + \setpdfdestname{#1}% + % + \ifx\pdfdestname\empty + \def\pdfdestname{Top}% no empty targets + \fi + % + \leavevmode + \ifnum\filenamelength>0 + % With default settings, + % XeTeX (xdvipdfmx) replaces link destination names with integers. + % In this case, the replaced destination names of + % remote PDFs are no longer known. In order to avoid a replacement, + % you can use xdvipdfmx's command line option `-C 0x0010'. + % If you use XeTeX 0.99996+ (TeX Live 2016+), + % this command line option is no longer necessary + % because we can use the `dvipdfmx:config' special. + \special{pdf:bann << /Border [0 0 0] /Type /Annot /Subtype /Link /A + << /S /GoToR /F (\the\filename.pdf) /D (\pdfdestname) >> >>}% + \else + \special{pdf:bann << /Border [0 0 0] /Type /Annot /Subtype /Link /A + << /S /GoTo /D (\pdfdestname) >> >>}% + \fi + }% + \setcolor{\linkcolor}% + \fi + \fi + {% + % Have to otherify everything special to allow the \csname to + % include an _ in the xref name, etc. + \indexnofonts + \turnoffactive + \def\value##1{##1}% + \expandafter\global\expandafter\let\expandafter\Xthisreftitle + \csname XR#1-title\endcsname + }% + % + % Float references are printed completely differently: "Figure 1.2" + % instead of "[somenode], p.3". \iffloat distinguishes them by + % \Xthisreftitle being set to a magic string. + \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}{}% + % Add a , if xref followed by a space + \if\space\noexpand\tokenafterxref ,% + \else\ifx\ \tokenafterxref ,% @TAB + \else\ifx\*\tokenafterxref ,% @* + \else\ifx\ \tokenafterxref ,% @SPACE + \else\ifx\ + \tokenafterxref ,% @NL + \else\ifx\tie\tokenafterxref ,% @tie + \fi\fi\fi\fi\fi\fi + \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 +} + +% \refx{NAME}{SUFFIX} - reference a cross-reference string named NAME. SUFFIX +% is output afterwards if non-empty. +\def\refx#1#2{% + \requireauxfile + {% + \indexnofonts + \otherbackslash + \def\value##1{##1}% + \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. Define a control +% sequence for a cross-reference target (we prepend XR to the control sequence +% name to avoid collisions). The value is the page number. If this is a float +% type, we have more work to do. +% +\def\xrdef#1#2{% + {% Expand the node or anchor name to remove control sequences. + % \turnoffactive stops 8-bit characters being changed to commands + % like @'e. \refx does the same to retrieve the value in the definition. + \indexnofonts + \turnoffactive + \def\value##1{##1}% + \xdef\safexrefname{#1}% + }% + % + \bgroup + \expandafter\gdef\csname XR\safexrefname\endcsname{#2}% + \egroup + % We put the \gdef inside a group to avoid the definitions building up on + % TeX's save stack, which can cause it to run out of space for aux files with + % thousands of lines. \gdef doesn't use the save stack, but \csname does + % when it defines an unknown control sequence as \relax. + % + % 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 +} + +% 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 at the beginning of the file. +% +\newif\iflinks \linkstrue % by default we want the aux files. +\let\novalidate = \linksfalse + +% Used when writing to the aux file, or when using data from it. +\def\requireauxfile{% + \iflinks + \tryauxfile + % Open the new aux file. TeX will close it automatically at exit. + \immediate\openout\auxfile=\jobname.aux + \fi + \global\let\requireauxfile=\relax % Only do this once. +} + +% 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 + % + % @ 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{% + \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 + % + % Nested footnotes are not supported in TeX, that would take a lot + % more work. (\startsavinginserts does not suffice.) + \let\footnote=\errfootnotenest + % + % 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=\txipagewidth + \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 + +\def\errfootnotenest{% + \errhelp=\EMsimple + \errmessage{Nested footnotes not supported in texinfo.tex, + even though they work in makeinfo; sorry} +} + +\def\errfootnoteheading{% + \errhelp=\EMsimple + \errmessage{Footnotes in chapters, sections, etc., are not supported} +} + +% 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 https://ctan.org/texarchive/macros/texinfo/texinfo/doc/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 + \def\xprocessmacroarg{\eatspaces}% in case we are being used via a macro + % 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 + % For pdfTeX and LuaTeX <= 0.80 + \dopdfimage{#1}{#2}{#3}% + \else + \ifx\XeTeXrevision\thisisundefined + % For epsf.tex + % \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}% + \else + % For XeTeX + \doxeteximage{#1}{#2}{#3}% + \fi + \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. + {% + \requireauxfile + \atdummies + % + \ifx\thisshortcaption\empty + \def\gtemp{\thiscaption}% + \else + \def\gtemp{\thisshortcaption}% + \fi + \immediate\write\auxfile{@xrdef{\floatlabel-lof}{\floatident + \ifx\gtemp\empty \else : \gtemp \fi}}% + }% + \fi + \egroup % end of \vtop + % + \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{% + \tex % read txi-??.tex file in plain TeX. + % Read the file by the name they passed if it exists. + \let_ = \normalunderscore % normal _ character for filename test + \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 +} +% +% 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 +} + +% XeTeX and LuaTeX can handle Unicode natively. +% Their default I/O uses UTF-8 sequences instead of a byte-wise operation. +% Other TeX engines' I/O (pdfTeX, etc.) is byte-wise. +% +\newif\iftxinativeunicodecapable +\newif\iftxiusebytewiseio + +\ifx\XeTeXrevision\thisisundefined + \ifx\luatexversion\thisisundefined + \txinativeunicodecapablefalse + \txiusebytewiseiotrue + \else + \txinativeunicodecapabletrue + \txiusebytewiseiofalse + \fi +\else + \txinativeunicodecapabletrue + \txiusebytewiseiofalse +\fi + +% Set I/O by bytes instead of UTF-8 sequence for XeTeX and LuaTex +% for non-UTF-8 (byte-wise) encodings. +% +\def\setbytewiseio{% + \ifx\XeTeXrevision\thisisundefined + \else + \XeTeXdefaultencoding "bytes" % For subsequent files to be read + \XeTeXinputencoding "bytes" % For document root file + % Unfortunately, there seems to be no corresponding XeTeX command for + % output encoding. This is a problem for auxiliary index and TOC files. + % The only solution would be perhaps to write out @U{...} sequences in + % place of non-ASCII characters. + \fi + + \ifx\luatexversion\thisisundefined + \else + \directlua{ + local utf8_char, byte, gsub = unicode.utf8.char, string.byte, string.gsub + local function convert_char (char) + return utf8_char(byte(char)) + end + + local function convert_line (line) + return gsub(line, ".", convert_char) + end + + callback.register("process_input_buffer", convert_line) + + local function convert_line_out (line) + local line_out = "" + for c in string.utfvalues(line) do + line_out = line_out .. string.char(c) + end + return line_out + end + + callback.register("process_output_buffer", convert_line_out) + } + \fi + + \txiusebytewiseiotrue +} + + +% 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. +% +\def\documentencoding{\parseargusing\filenamecatcodes\documentencodingzzz} +\def\documentencodingzzz#1{% + % + % 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 + \iftxinativeunicodecapable + \setbytewiseio + \fi + \setnonasciicharscatcode\active + \lattwochardefs + % + \else \ifx \declaredencoding \latone + \iftxinativeunicodecapable + \setbytewiseio + \fi + \setnonasciicharscatcode\active + \latonechardefs + % + \else \ifx \declaredencoding \latnine + \iftxinativeunicodecapable + \setbytewiseio + \fi + \setnonasciicharscatcode\active + \latninechardefs + % + \else \ifx \declaredencoding \utfeight + \iftxinativeunicodecapable + % For native Unicode handling (XeTeX and LuaTeX) + \nativeunicodechardefs + \else + % For treating UTF-8 as byte sequences (TeX, eTeX and pdfTeX) + \setnonasciicharscatcode\active + % since we already invoked \utfeightchardefs at the top level + % (below), do not re-invoke it, otherwise our check for duplicated + % definitions gets triggered. Making non-ascii chars active is + % sufficient. + \fi + % + \else + \message{Ignoring unknown document encoding: #1.}% + % + \fi % utfeight + \fi % latnine + \fi % latone + \fi % lattwo + \fi % ascii + % + \ifx\XeTeXrevision\thisisundefined + \else + \ifx \declaredencoding \utfeight + \else + \ifx \declaredencoding \ascii + \else + \message{Warning: XeTeX with non-UTF-8 encodings cannot handle % + non-ASCII characters in auxiliary files.}% + \fi + \fi + \fi +} + +% emacs-page +% A message to be logged when using a character that isn't available +% the default font encoding (OT1). +% +\def\missingcharmsg#1{\message{Character missing, sorry: #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 +% + +\def\gdefchar#1#2{% +\gdef#1{% + \ifpassthroughchars + \string#1% + \else + #2% + \fi +}} + +% Latin1 (ISO-8859-1) character definitions. +\def\latonechardefs{% + \gdefchar^^a0{\tie} + \gdefchar^^a1{\exclamdown} + \gdefchar^^a2{{\tcfont \char162}} % cent + \gdefchar^^a3{\pounds{}} + \gdefchar^^a4{{\tcfont \char164}} % currency + \gdefchar^^a5{{\tcfont \char165}} % yen + \gdefchar^^a6{{\tcfont \char166}} % broken bar + \gdefchar^^a7{\S} + \gdefchar^^a8{\"{}} + \gdefchar^^a9{\copyright{}} + \gdefchar^^aa{\ordf} + \gdefchar^^ab{\guillemetleft{}} + \gdefchar^^ac{\ensuremath\lnot} + \gdefchar^^ad{\-} + \gdefchar^^ae{\registeredsymbol{}} + \gdefchar^^af{\={}} + % + \gdefchar^^b0{\textdegree} + \gdefchar^^b1{$\pm$} + \gdefchar^^b2{$^2$} + \gdefchar^^b3{$^3$} + \gdefchar^^b4{\'{}} + \gdefchar^^b5{$\mu$} + \gdefchar^^b6{\P} + \gdefchar^^b7{\ensuremath\cdot} + \gdefchar^^b8{\cedilla\ } + \gdefchar^^b9{$^1$} + \gdefchar^^ba{\ordm} + \gdefchar^^bb{\guillemetright{}} + \gdefchar^^bc{$1\over4$} + \gdefchar^^bd{$1\over2$} + \gdefchar^^be{$3\over4$} + \gdefchar^^bf{\questiondown} + % + \gdefchar^^c0{\`A} + \gdefchar^^c1{\'A} + \gdefchar^^c2{\^A} + \gdefchar^^c3{\~A} + \gdefchar^^c4{\"A} + \gdefchar^^c5{\ringaccent A} + \gdefchar^^c6{\AE} + \gdefchar^^c7{\cedilla C} + \gdefchar^^c8{\`E} + \gdefchar^^c9{\'E} + \gdefchar^^ca{\^E} + \gdefchar^^cb{\"E} + \gdefchar^^cc{\`I} + \gdefchar^^cd{\'I} + \gdefchar^^ce{\^I} + \gdefchar^^cf{\"I} + % + \gdefchar^^d0{\DH} + \gdefchar^^d1{\~N} + \gdefchar^^d2{\`O} + \gdefchar^^d3{\'O} + \gdefchar^^d4{\^O} + \gdefchar^^d5{\~O} + \gdefchar^^d6{\"O} + \gdefchar^^d7{$\times$} + \gdefchar^^d8{\O} + \gdefchar^^d9{\`U} + \gdefchar^^da{\'U} + \gdefchar^^db{\^U} + \gdefchar^^dc{\"U} + \gdefchar^^dd{\'Y} + \gdefchar^^de{\TH} + \gdefchar^^df{\ss} + % + \gdefchar^^e0{\`a} + \gdefchar^^e1{\'a} + \gdefchar^^e2{\^a} + \gdefchar^^e3{\~a} + \gdefchar^^e4{\"a} + \gdefchar^^e5{\ringaccent a} + \gdefchar^^e6{\ae} + \gdefchar^^e7{\cedilla c} + \gdefchar^^e8{\`e} + \gdefchar^^e9{\'e} + \gdefchar^^ea{\^e} + \gdefchar^^eb{\"e} + \gdefchar^^ec{\`{\dotless i}} + \gdefchar^^ed{\'{\dotless i}} + \gdefchar^^ee{\^{\dotless i}} + \gdefchar^^ef{\"{\dotless i}} + % + \gdefchar^^f0{\dh} + \gdefchar^^f1{\~n} + \gdefchar^^f2{\`o} + \gdefchar^^f3{\'o} + \gdefchar^^f4{\^o} + \gdefchar^^f5{\~o} + \gdefchar^^f6{\"o} + \gdefchar^^f7{$\div$} + \gdefchar^^f8{\o} + \gdefchar^^f9{\`u} + \gdefchar^^fa{\'u} + \gdefchar^^fb{\^u} + \gdefchar^^fc{\"u} + \gdefchar^^fd{\'y} + \gdefchar^^fe{\th} + \gdefchar^^ff{\"y} +} + +% Latin9 (ISO-8859-15) encoding character definitions. +\def\latninechardefs{% + % Encoding is almost identical to Latin1. + \latonechardefs + % + \gdefchar^^a4{\euro{}} + \gdefchar^^a6{\v S} + \gdefchar^^a8{\v s} + \gdefchar^^b4{\v Z} + \gdefchar^^b8{\v z} + \gdefchar^^bc{\OE} + \gdefchar^^bd{\oe} + \gdefchar^^be{\"Y} +} + +% Latin2 (ISO-8859-2) character definitions. +\def\lattwochardefs{% + \gdefchar^^a0{\tie} + \gdefchar^^a1{\ogonek{A}} + \gdefchar^^a2{\u{}} + \gdefchar^^a3{\L} + \gdefchar^^a4{\missingcharmsg{CURRENCY SIGN}} + \gdefchar^^a5{\v L} + \gdefchar^^a6{\'S} + \gdefchar^^a7{\S} + \gdefchar^^a8{\"{}} + \gdefchar^^a9{\v S} + \gdefchar^^aa{\cedilla S} + \gdefchar^^ab{\v T} + \gdefchar^^ac{\'Z} + \gdefchar^^ad{\-} + \gdefchar^^ae{\v Z} + \gdefchar^^af{\dotaccent Z} + % + \gdefchar^^b0{\textdegree{}} + \gdefchar^^b1{\ogonek{a}} + \gdefchar^^b2{\ogonek{ }} + \gdefchar^^b3{\l} + \gdefchar^^b4{\'{}} + \gdefchar^^b5{\v l} + \gdefchar^^b6{\'s} + \gdefchar^^b7{\v{}} + \gdefchar^^b8{\cedilla\ } + \gdefchar^^b9{\v s} + \gdefchar^^ba{\cedilla s} + \gdefchar^^bb{\v t} + \gdefchar^^bc{\'z} + \gdefchar^^bd{\H{}} + \gdefchar^^be{\v z} + \gdefchar^^bf{\dotaccent z} + % + \gdefchar^^c0{\'R} + \gdefchar^^c1{\'A} + \gdefchar^^c2{\^A} + \gdefchar^^c3{\u A} + \gdefchar^^c4{\"A} + \gdefchar^^c5{\'L} + \gdefchar^^c6{\'C} + \gdefchar^^c7{\cedilla C} + \gdefchar^^c8{\v C} + \gdefchar^^c9{\'E} + \gdefchar^^ca{\ogonek{E}} + \gdefchar^^cb{\"E} + \gdefchar^^cc{\v E} + \gdefchar^^cd{\'I} + \gdefchar^^ce{\^I} + \gdefchar^^cf{\v D} + % + \gdefchar^^d0{\DH} + \gdefchar^^d1{\'N} + \gdefchar^^d2{\v N} + \gdefchar^^d3{\'O} + \gdefchar^^d4{\^O} + \gdefchar^^d5{\H O} + \gdefchar^^d6{\"O} + \gdefchar^^d7{$\times$} + \gdefchar^^d8{\v R} + \gdefchar^^d9{\ringaccent U} + \gdefchar^^da{\'U} + \gdefchar^^db{\H U} + \gdefchar^^dc{\"U} + \gdefchar^^dd{\'Y} + \gdefchar^^de{\cedilla T} + \gdefchar^^df{\ss} + % + \gdefchar^^e0{\'r} + \gdefchar^^e1{\'a} + \gdefchar^^e2{\^a} + \gdefchar^^e3{\u a} + \gdefchar^^e4{\"a} + \gdefchar^^e5{\'l} + \gdefchar^^e6{\'c} + \gdefchar^^e7{\cedilla c} + \gdefchar^^e8{\v c} + \gdefchar^^e9{\'e} + \gdefchar^^ea{\ogonek{e}} + \gdefchar^^eb{\"e} + \gdefchar^^ec{\v e} + \gdefchar^^ed{\'{\dotless{i}}} + \gdefchar^^ee{\^{\dotless{i}}} + \gdefchar^^ef{\v d} + % + \gdefchar^^f0{\dh} + \gdefchar^^f1{\'n} + \gdefchar^^f2{\v n} + \gdefchar^^f3{\'o} + \gdefchar^^f4{\^o} + \gdefchar^^f5{\H o} + \gdefchar^^f6{\"o} + \gdefchar^^f7{$\div$} + \gdefchar^^f8{\v r} + \gdefchar^^f9{\ringaccent u} + \gdefchar^^fa{\'u} + \gdefchar^^fb{\H u} + \gdefchar^^fc{\"u} + \gdefchar^^fd{\'y} + \gdefchar^^fe{\cedilla t} + \gdefchar^^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 +} + +% Give non-ASCII bytes the active definitions for processing UTF-8 sequences +\begingroup + \catcode`\~13 + \catcode`\$12 + \catcode`\"12 + + % Loop from \countUTFx to \countUTFy, performing \UTFviiiTmp + % substituting ~ and $ with a character token of that value. + \def\UTFviiiLoop{% + \global\catcode\countUTFx\active + \uccode`\~\countUTFx + \uccode`\$\countUTFx + \uppercase\expandafter{\UTFviiiTmp}% + \advance\countUTFx by 1 + \ifnum\countUTFx < \countUTFy + \expandafter\UTFviiiLoop + \fi} + + % For bytes other than the first in a UTF-8 sequence. Not expected to + % be expanded except when writing to auxiliary files. + \countUTFx = "80 + \countUTFy = "C2 + \def\UTFviiiTmp{% + \gdef~{% + \ifpassthroughchars $\fi}}% + \UTFviiiLoop + + \countUTFx = "C2 + \countUTFy = "E0 + \def\UTFviiiTmp{% + \gdef~{% + \ifpassthroughchars $% + \else\expandafter\UTFviiiTwoOctets\expandafter$\fi}}% + \UTFviiiLoop + + \countUTFx = "E0 + \countUTFy = "F0 + \def\UTFviiiTmp{% + \gdef~{% + \ifpassthroughchars $% + \else\expandafter\UTFviiiThreeOctets\expandafter$\fi}}% + \UTFviiiLoop + + \countUTFx = "F0 + \countUTFy = "F4 + \def\UTFviiiTmp{% + \gdef~{% + \ifpassthroughchars $% + \else\expandafter\UTFviiiFourOctets\expandafter$\fi + }}% + \UTFviiiLoop +\endgroup + +\def\globallet{\global\let} % save some \expandafter's below + +% @U{xxxx} to produce U+xxxx, if we support it. +\def\U#1{% + \expandafter\ifx\csname uni:#1\endcsname \relax + \iftxinativeunicodecapable + % All Unicode characters can be used if native Unicode handling is + % active. However, if the font does not have the glyph, + % letters are missing. + \begingroup + \uccode`\.="#1\relax + \uppercase{.} + \endgroup + \else + \errhelp = \EMsimple + \errmessage{Unicode character U+#1 not supported, sorry}% + \fi + \else + \csname uni:#1\endcsname + \fi +} + +% These macros are used here to construct the name of a control +% sequence to be defined. +\def\UTFviiiTwoOctetsName#1#2{% + \csname u8:#1\string #2\endcsname}% +\def\UTFviiiThreeOctetsName#1#2#3{% + \csname u8:#1\string #2\string #3\endcsname}% +\def\UTFviiiFourOctetsName#1#2#3#4{% + \csname u8:#1\string #2\string #3\string #4\endcsname}% + +% For UTF-8 byte sequences (TeX, e-TeX and pdfTeX), +% provide a definition macro to replace a Unicode character; +% this gets used by the @U command +% +\begingroup + \catcode`\"=12 + \catcode`\<=12 + \catcode`\.=12 + \catcode`\,=12 + \catcode`\;=12 + \catcode`\!=12 + \catcode`\~=13 + \gdef\DeclareUnicodeCharacterUTFviii#1#2{% + \countUTFz = "#1\relax + \begingroup + \parseXMLCharref + + % Give \u8:... its definition. The sequence of seven \expandafter's + % expands after the \gdef three times, e.g. + % + % 1. \UTFviiTwoOctetsName B1 B2 + % 2. \csname u8:B1 \string B2 \endcsname + % 3. \u8: B1 B2 (a single control sequence token) + % + \expandafter\expandafter + \expandafter\expandafter + \expandafter\expandafter + \expandafter\gdef \UTFviiiTmp{#2}% + % + \expandafter\ifx\csname uni:#1\endcsname \relax \else + \message{Internal error, already defined: #1}% + \fi + % + % define an additional control sequence for this code point. + \expandafter\globallet\csname uni:#1\endcsname \UTFviiiTmp + \endgroup} + % + % Given the value in \countUTFz as a Unicode code point, set \UTFviiiTmp + % to the corresponding UTF-8 sequence. + \gdef\parseXMLCharref{% + \ifnum\countUTFz < "A0\relax + \errhelp = \EMsimple + \errmessage{Cannot define Unicode char value < 00A0}% + \else\ifnum\countUTFz < "800\relax + \parseUTFviiiA,% + \parseUTFviiiB C\UTFviiiTwoOctetsName.,% + \else\ifnum\countUTFz < "10000\relax + \parseUTFviiiA;% + \parseUTFviiiA,% + \parseUTFviiiB E\UTFviiiThreeOctetsName.{,;}% + \else + \parseUTFviiiA;% + \parseUTFviiiA,% + \parseUTFviiiA!% + \parseUTFviiiB F\UTFviiiFourOctetsName.{!,;}% + \fi\fi\fi + } + + % Extract a byte from the end of the UTF-8 representation of \countUTFx. + % It must be a non-initial byte in the sequence. + % Change \uccode of #1 for it to be used in \parseUTFviiiB as one + % of the bytes. + \gdef\parseUTFviiiA#1{% + \countUTFx = \countUTFz + \divide\countUTFz by 64 + \countUTFy = \countUTFz % Save to be the future value of \countUTFz. + \multiply\countUTFz by 64 + + % \countUTFz is now \countUTFx with the last 5 bits cleared. Subtract + % in order to get the last five bits. + \advance\countUTFx by -\countUTFz + + % Convert this to the byte in the UTF-8 sequence. + \advance\countUTFx by 128 + \uccode `#1\countUTFx + \countUTFz = \countUTFy} + + % Used to put a UTF-8 byte sequence into \UTFviiiTmp + % #1 is the increment for \countUTFz to yield a the first byte of the UTF-8 + % sequence. + % #2 is one of the \UTFviii*OctetsName macros. + % #3 is always a full stop (.) + % #4 is a template for the other bytes in the sequence. The values for these + % bytes is substituted in here with \uppercase using the \uccode's. + \gdef\parseUTFviiiB#1#2#3#4{% + \advance\countUTFz by "#10\relax + \uccode `#3\countUTFz + \uppercase{\gdef\UTFviiiTmp{#2#3#4}}} +\endgroup + +% For native Unicode handling (XeTeX and LuaTeX), +% provide a definition macro that sets a catcode to `other' non-globally +% +\def\DeclareUnicodeCharacterNativeOther#1#2{% + \catcode"#1=\other +} + +% https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_M +% U+0000..U+007F = https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block) +% U+0080..U+00FF = https://en.wikipedia.org/wiki/Latin-1_Supplement_(Unicode_block) +% U+0100..U+017F = https://en.wikipedia.org/wiki/Latin_Extended-A +% U+0180..U+024F = https://en.wikipedia.org/wiki/Latin_Extended-B +% +% Many of our renditions are less than wonderful, and all the missing +% characters are available somewhere. Loading the necessary fonts +% awaits user request. We can't truly support Unicode without +% reimplementing everything that's been done in LaTeX for many years, +% plus probably using luatex or xetex, and who knows what else. +% We won't be doing that here in this simple file. But we can try to at +% least make most of the characters not bomb out. +% +\def\unicodechardefs{% + \DeclareUnicodeCharacter{00A0}{\tie}% + \DeclareUnicodeCharacter{00A1}{\exclamdown}% + \DeclareUnicodeCharacter{00A2}{{\tcfont \char162}}% 0242=cent + \DeclareUnicodeCharacter{00A3}{\pounds{}}% + \DeclareUnicodeCharacter{00A4}{{\tcfont \char164}}% 0244=currency + \DeclareUnicodeCharacter{00A5}{{\tcfont \char165}}% 0245=yen + \DeclareUnicodeCharacter{00A6}{{\tcfont \char166}}% 0246=brokenbar + \DeclareUnicodeCharacter{00A7}{\S}% + \DeclareUnicodeCharacter{00A8}{\"{ }}% + \DeclareUnicodeCharacter{00A9}{\copyright{}}% + \DeclareUnicodeCharacter{00AA}{\ordf}% + \DeclareUnicodeCharacter{00AB}{\guillemetleft{}}% + \DeclareUnicodeCharacter{00AC}{\ensuremath\lnot}% + \DeclareUnicodeCharacter{00AD}{\-}% + \DeclareUnicodeCharacter{00AE}{\registeredsymbol{}}% + \DeclareUnicodeCharacter{00AF}{\={ }}% + % + \DeclareUnicodeCharacter{00B0}{\ringaccent{ }}% + \DeclareUnicodeCharacter{00B1}{\ensuremath\pm}% + \DeclareUnicodeCharacter{00B2}{$^2$}% + \DeclareUnicodeCharacter{00B3}{$^3$}% + \DeclareUnicodeCharacter{00B4}{\'{ }}% + \DeclareUnicodeCharacter{00B5}{$\mu$}% + \DeclareUnicodeCharacter{00B6}{\P}% + \DeclareUnicodeCharacter{00B7}{\ensuremath\cdot}% + \DeclareUnicodeCharacter{00B8}{\cedilla{ }}% + \DeclareUnicodeCharacter{00B9}{$^1$}% + \DeclareUnicodeCharacter{00BA}{\ordm}% + \DeclareUnicodeCharacter{00BB}{\guillemetright{}}% + \DeclareUnicodeCharacter{00BC}{$1\over4$}% + \DeclareUnicodeCharacter{00BD}{$1\over2$}% + \DeclareUnicodeCharacter{00BE}{$3\over4$}% + \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{00D7}{\ensuremath\times}% + \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{00F7}{\ensuremath\div}% + \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{010A}{\dotaccent{C}}% + \DeclareUnicodeCharacter{010B}{\dotaccent{c}}% + \DeclareUnicodeCharacter{010C}{\v{C}}% + \DeclareUnicodeCharacter{010D}{\v{c}}% + \DeclareUnicodeCharacter{010E}{\v{D}}% + \DeclareUnicodeCharacter{010F}{d'}% + % + \DeclareUnicodeCharacter{0110}{\DH}% + \DeclareUnicodeCharacter{0111}{\dh}% + \DeclareUnicodeCharacter{0112}{\=E}% + \DeclareUnicodeCharacter{0113}{\=e}% + \DeclareUnicodeCharacter{0114}{\u{E}}% + \DeclareUnicodeCharacter{0115}{\u{e}}% + \DeclareUnicodeCharacter{0116}{\dotaccent{E}}% + \DeclareUnicodeCharacter{0117}{\dotaccent{e}}% + \DeclareUnicodeCharacter{0118}{\ogonek{E}}% + \DeclareUnicodeCharacter{0119}{\ogonek{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{0122}{\cedilla{G}}% + \DeclareUnicodeCharacter{0123}{\cedilla{g}}% + \DeclareUnicodeCharacter{0124}{\^H}% + \DeclareUnicodeCharacter{0125}{\^h}% + \DeclareUnicodeCharacter{0126}{\missingcharmsg{H WITH STROKE}}% + \DeclareUnicodeCharacter{0127}{\missingcharmsg{h WITH STROKE}}% + \DeclareUnicodeCharacter{0128}{\~I}% + \DeclareUnicodeCharacter{0129}{\~{\dotless{i}}}% + \DeclareUnicodeCharacter{012A}{\=I}% + \DeclareUnicodeCharacter{012B}{\={\dotless{i}}}% + \DeclareUnicodeCharacter{012C}{\u{I}}% + \DeclareUnicodeCharacter{012D}{\u{\dotless{i}}}% + \DeclareUnicodeCharacter{012E}{\ogonek{I}}% + \DeclareUnicodeCharacter{012F}{\ogonek{i}}% + % + \DeclareUnicodeCharacter{0130}{\dotaccent{I}}% + \DeclareUnicodeCharacter{0131}{\dotless{i}}% + \DeclareUnicodeCharacter{0132}{IJ}% + \DeclareUnicodeCharacter{0133}{ij}% + \DeclareUnicodeCharacter{0134}{\^J}% + \DeclareUnicodeCharacter{0135}{\^{\dotless{j}}}% + \DeclareUnicodeCharacter{0136}{\cedilla{K}}% + \DeclareUnicodeCharacter{0137}{\cedilla{k}}% + \DeclareUnicodeCharacter{0138}{\ensuremath\kappa}% + \DeclareUnicodeCharacter{0139}{\'L}% + \DeclareUnicodeCharacter{013A}{\'l}% + \DeclareUnicodeCharacter{013B}{\cedilla{L}}% + \DeclareUnicodeCharacter{013C}{\cedilla{l}}% + \DeclareUnicodeCharacter{013D}{L'}% should kern + \DeclareUnicodeCharacter{013E}{l'}% should kern + \DeclareUnicodeCharacter{013F}{L\U{00B7}}% + % + \DeclareUnicodeCharacter{0140}{l\U{00B7}}% + \DeclareUnicodeCharacter{0141}{\L}% + \DeclareUnicodeCharacter{0142}{\l}% + \DeclareUnicodeCharacter{0143}{\'N}% + \DeclareUnicodeCharacter{0144}{\'n}% + \DeclareUnicodeCharacter{0145}{\cedilla{N}}% + \DeclareUnicodeCharacter{0146}{\cedilla{n}}% + \DeclareUnicodeCharacter{0147}{\v{N}}% + \DeclareUnicodeCharacter{0148}{\v{n}}% + \DeclareUnicodeCharacter{0149}{'n}% + \DeclareUnicodeCharacter{014A}{\missingcharmsg{ENG}}% + \DeclareUnicodeCharacter{014B}{\missingcharmsg{eng}}% + \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{0156}{\cedilla{R}}% + \DeclareUnicodeCharacter{0157}{\cedilla{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{0165}{\v{t}}% + \DeclareUnicodeCharacter{0166}{\missingcharmsg{H WITH STROKE}}% + \DeclareUnicodeCharacter{0167}{\missingcharmsg{h WITH STROKE}}% + \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{0172}{\ogonek{U}}% + \DeclareUnicodeCharacter{0173}{\ogonek{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{017F}{\missingcharmsg{LONG S}}% + % + \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{ }}% + % + % Greek letters upper case + \DeclareUnicodeCharacter{0391}{{\it A}}% + \DeclareUnicodeCharacter{0392}{{\it B}}% + \DeclareUnicodeCharacter{0393}{\ensuremath{\mit\Gamma}}% + \DeclareUnicodeCharacter{0394}{\ensuremath{\mit\Delta}}% + \DeclareUnicodeCharacter{0395}{{\it E}}% + \DeclareUnicodeCharacter{0396}{{\it Z}}% + \DeclareUnicodeCharacter{0397}{{\it H}}% + \DeclareUnicodeCharacter{0398}{\ensuremath{\mit\Theta}}% + \DeclareUnicodeCharacter{0399}{{\it I}}% + \DeclareUnicodeCharacter{039A}{{\it K}}% + \DeclareUnicodeCharacter{039B}{\ensuremath{\mit\Lambda}}% + \DeclareUnicodeCharacter{039C}{{\it M}}% + \DeclareUnicodeCharacter{039D}{{\it N}}% + \DeclareUnicodeCharacter{039E}{\ensuremath{\mit\Xi}}% + \DeclareUnicodeCharacter{039F}{{\it O}}% + \DeclareUnicodeCharacter{03A0}{\ensuremath{\mit\Pi}}% + \DeclareUnicodeCharacter{03A1}{{\it P}}% + %\DeclareUnicodeCharacter{03A2}{} % none - corresponds to final sigma + \DeclareUnicodeCharacter{03A3}{\ensuremath{\mit\Sigma}}% + \DeclareUnicodeCharacter{03A4}{{\it T}}% + \DeclareUnicodeCharacter{03A5}{\ensuremath{\mit\Upsilon}}% + \DeclareUnicodeCharacter{03A6}{\ensuremath{\mit\Phi}}% + \DeclareUnicodeCharacter{03A7}{{\it X}}% + \DeclareUnicodeCharacter{03A8}{\ensuremath{\mit\Psi}}% + \DeclareUnicodeCharacter{03A9}{\ensuremath{\mit\Omega}}% + % + % Vowels with accents + \DeclareUnicodeCharacter{0390}{\ensuremath{\ddot{\acute\iota}}}% + \DeclareUnicodeCharacter{03AC}{\ensuremath{\acute\alpha}}% + \DeclareUnicodeCharacter{03AD}{\ensuremath{\acute\epsilon}}% + \DeclareUnicodeCharacter{03AE}{\ensuremath{\acute\eta}}% + \DeclareUnicodeCharacter{03AF}{\ensuremath{\acute\iota}}% + \DeclareUnicodeCharacter{03B0}{\ensuremath{\acute{\ddot\upsilon}}}% + % + % Standalone accent + \DeclareUnicodeCharacter{0384}{\ensuremath{\acute{\ }}}% + % + % Greek letters lower case + \DeclareUnicodeCharacter{03B1}{\ensuremath\alpha}% + \DeclareUnicodeCharacter{03B2}{\ensuremath\beta}% + \DeclareUnicodeCharacter{03B3}{\ensuremath\gamma}% + \DeclareUnicodeCharacter{03B4}{\ensuremath\delta}% + \DeclareUnicodeCharacter{03B5}{\ensuremath\epsilon}% + \DeclareUnicodeCharacter{03B6}{\ensuremath\zeta}% + \DeclareUnicodeCharacter{03B7}{\ensuremath\eta}% + \DeclareUnicodeCharacter{03B8}{\ensuremath\theta}% + \DeclareUnicodeCharacter{03B9}{\ensuremath\iota}% + \DeclareUnicodeCharacter{03BA}{\ensuremath\kappa}% + \DeclareUnicodeCharacter{03BB}{\ensuremath\lambda}% + \DeclareUnicodeCharacter{03BC}{\ensuremath\mu}% + \DeclareUnicodeCharacter{03BD}{\ensuremath\nu}% + \DeclareUnicodeCharacter{03BE}{\ensuremath\xi}% + \DeclareUnicodeCharacter{03BF}{{\it o}}% omicron + \DeclareUnicodeCharacter{03C0}{\ensuremath\pi}% + \DeclareUnicodeCharacter{03C1}{\ensuremath\rho}% + \DeclareUnicodeCharacter{03C2}{\ensuremath\varsigma}% + \DeclareUnicodeCharacter{03C3}{\ensuremath\sigma}% + \DeclareUnicodeCharacter{03C4}{\ensuremath\tau}% + \DeclareUnicodeCharacter{03C5}{\ensuremath\upsilon}% + \DeclareUnicodeCharacter{03C6}{\ensuremath\phi}% + \DeclareUnicodeCharacter{03C7}{\ensuremath\chi}% + \DeclareUnicodeCharacter{03C8}{\ensuremath\psi}% + \DeclareUnicodeCharacter{03C9}{\ensuremath\omega}% + % + % More Greek vowels with accents + \DeclareUnicodeCharacter{03CA}{\ensuremath{\ddot\iota}}% + \DeclareUnicodeCharacter{03CB}{\ensuremath{\ddot\upsilon}}% + \DeclareUnicodeCharacter{03CC}{\ensuremath{\acute o}}% + \DeclareUnicodeCharacter{03CD}{\ensuremath{\acute\upsilon}}% + \DeclareUnicodeCharacter{03CE}{\ensuremath{\acute\omega}}% + % + % Variant Greek letters + \DeclareUnicodeCharacter{03D1}{\ensuremath\vartheta}% + \DeclareUnicodeCharacter{03D6}{\ensuremath\varpi}% + \DeclareUnicodeCharacter{03F1}{\ensuremath\varrho}% + % + \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}% + % + % Punctuation + \DeclareUnicodeCharacter{2013}{--}% + \DeclareUnicodeCharacter{2014}{---}% + \DeclareUnicodeCharacter{2018}{\quoteleft{}}% + \DeclareUnicodeCharacter{2019}{\quoteright{}}% + \DeclareUnicodeCharacter{201A}{\quotesinglbase{}}% + \DeclareUnicodeCharacter{201C}{\quotedblleft{}}% + \DeclareUnicodeCharacter{201D}{\quotedblright{}}% + \DeclareUnicodeCharacter{201E}{\quotedblbase{}}% + \DeclareUnicodeCharacter{2020}{\ensuremath\dagger}% + \DeclareUnicodeCharacter{2021}{\ensuremath\ddagger}% + \DeclareUnicodeCharacter{2022}{\bullet{}}% + \DeclareUnicodeCharacter{202F}{\thinspace}% + \DeclareUnicodeCharacter{2026}{\dots{}}% + \DeclareUnicodeCharacter{2039}{\guilsinglleft{}}% + \DeclareUnicodeCharacter{203A}{\guilsinglright{}}% + % + \DeclareUnicodeCharacter{20AC}{\euro{}}% + % + \DeclareUnicodeCharacter{2192}{\expansion{}}% + \DeclareUnicodeCharacter{21D2}{\result{}}% + % + % Mathematical symbols + \DeclareUnicodeCharacter{2200}{\ensuremath\forall}% + \DeclareUnicodeCharacter{2203}{\ensuremath\exists}% + \DeclareUnicodeCharacter{2208}{\ensuremath\in}% + \DeclareUnicodeCharacter{2212}{\minus{}}% + \DeclareUnicodeCharacter{2217}{\ast}% + \DeclareUnicodeCharacter{221E}{\ensuremath\infty}% + \DeclareUnicodeCharacter{2225}{\ensuremath\parallel}% + \DeclareUnicodeCharacter{2227}{\ensuremath\wedge}% + \DeclareUnicodeCharacter{2229}{\ensuremath\cap}% + \DeclareUnicodeCharacter{2261}{\equiv{}}% + \DeclareUnicodeCharacter{2264}{\ensuremath\leq}% + \DeclareUnicodeCharacter{2265}{\ensuremath\geq}% + \DeclareUnicodeCharacter{2282}{\ensuremath\subset}% + \DeclareUnicodeCharacter{2287}{\ensuremath\supseteq}% + % + \DeclareUnicodeCharacter{2016}{\ensuremath\Vert}% + \DeclareUnicodeCharacter{2032}{\ensuremath\prime}% + \DeclareUnicodeCharacter{210F}{\ensuremath\hbar}% + \DeclareUnicodeCharacter{2111}{\ensuremath\Im}% + \DeclareUnicodeCharacter{2113}{\ensuremath\ell}% + \DeclareUnicodeCharacter{2118}{\ensuremath\wp}% + \DeclareUnicodeCharacter{211C}{\ensuremath\Re}% + \DeclareUnicodeCharacter{2135}{\ensuremath\aleph}% + \DeclareUnicodeCharacter{2190}{\ensuremath\leftarrow}% + \DeclareUnicodeCharacter{2191}{\ensuremath\uparrow}% + \DeclareUnicodeCharacter{2193}{\ensuremath\downarrow}% + \DeclareUnicodeCharacter{2194}{\ensuremath\leftrightarrow}% + \DeclareUnicodeCharacter{2195}{\ensuremath\updownarrow}% + \DeclareUnicodeCharacter{2196}{\ensuremath\nwarrow}% + \DeclareUnicodeCharacter{2197}{\ensuremath\nearrow}% + \DeclareUnicodeCharacter{2198}{\ensuremath\searrow}% + \DeclareUnicodeCharacter{2199}{\ensuremath\swarrow}% + \DeclareUnicodeCharacter{21A6}{\ensuremath\mapsto}% + \DeclareUnicodeCharacter{21A9}{\ensuremath\hookleftarrow}% + \DeclareUnicodeCharacter{21AA}{\ensuremath\hookrightarrow}% + \DeclareUnicodeCharacter{21BC}{\ensuremath\leftharpoonup}% + \DeclareUnicodeCharacter{21BD}{\ensuremath\leftharpoondown}% + \DeclareUnicodeCharacter{21C0}{\ensuremath\rightharpoonup}% + \DeclareUnicodeCharacter{21C1}{\ensuremath\rightharpoondown}% + \DeclareUnicodeCharacter{21CC}{\ensuremath\rightleftharpoons}% + \DeclareUnicodeCharacter{21D0}{\ensuremath\Leftarrow}% + \DeclareUnicodeCharacter{21D1}{\ensuremath\Uparrow}% + \DeclareUnicodeCharacter{21D3}{\ensuremath\Downarrow}% + \DeclareUnicodeCharacter{21D4}{\ensuremath\Leftrightarrow}% + \DeclareUnicodeCharacter{21D5}{\ensuremath\Updownarrow}% + \DeclareUnicodeCharacter{2202}{\ensuremath\partial}% + \DeclareUnicodeCharacter{2205}{\ensuremath\emptyset}% + \DeclareUnicodeCharacter{2207}{\ensuremath\nabla}% + \DeclareUnicodeCharacter{2209}{\ensuremath\notin}% + \DeclareUnicodeCharacter{220B}{\ensuremath\owns}% + \DeclareUnicodeCharacter{220F}{\ensuremath\prod}% + \DeclareUnicodeCharacter{2210}{\ensuremath\coprod}% + \DeclareUnicodeCharacter{2211}{\ensuremath\sum}% + \DeclareUnicodeCharacter{2213}{\ensuremath\mp}% + \DeclareUnicodeCharacter{2218}{\ensuremath\circ}% + \DeclareUnicodeCharacter{221A}{\ensuremath\surd}% + \DeclareUnicodeCharacter{221D}{\ensuremath\propto}% + \DeclareUnicodeCharacter{2220}{\ensuremath\angle}% + \DeclareUnicodeCharacter{2223}{\ensuremath\mid}% + \DeclareUnicodeCharacter{2228}{\ensuremath\vee}% + \DeclareUnicodeCharacter{222A}{\ensuremath\cup}% + \DeclareUnicodeCharacter{222B}{\ensuremath\smallint}% + \DeclareUnicodeCharacter{222E}{\ensuremath\oint}% + \DeclareUnicodeCharacter{223C}{\ensuremath\sim}% + \DeclareUnicodeCharacter{2240}{\ensuremath\wr}% + \DeclareUnicodeCharacter{2243}{\ensuremath\simeq}% + \DeclareUnicodeCharacter{2245}{\ensuremath\cong}% + \DeclareUnicodeCharacter{2248}{\ensuremath\approx}% + \DeclareUnicodeCharacter{224D}{\ensuremath\asymp}% + \DeclareUnicodeCharacter{2250}{\ensuremath\doteq}% + \DeclareUnicodeCharacter{2260}{\ensuremath\neq}% + \DeclareUnicodeCharacter{226A}{\ensuremath\ll}% + \DeclareUnicodeCharacter{226B}{\ensuremath\gg}% + \DeclareUnicodeCharacter{227A}{\ensuremath\prec}% + \DeclareUnicodeCharacter{227B}{\ensuremath\succ}% + \DeclareUnicodeCharacter{2283}{\ensuremath\supset}% + \DeclareUnicodeCharacter{2286}{\ensuremath\subseteq}% + \DeclareUnicodeCharacter{228E}{\ensuremath\uplus}% + \DeclareUnicodeCharacter{2291}{\ensuremath\sqsubseteq}% + \DeclareUnicodeCharacter{2292}{\ensuremath\sqsupseteq}% + \DeclareUnicodeCharacter{2293}{\ensuremath\sqcap}% + \DeclareUnicodeCharacter{2294}{\ensuremath\sqcup}% + \DeclareUnicodeCharacter{2295}{\ensuremath\oplus}% + \DeclareUnicodeCharacter{2296}{\ensuremath\ominus}% + \DeclareUnicodeCharacter{2297}{\ensuremath\otimes}% + \DeclareUnicodeCharacter{2298}{\ensuremath\oslash}% + \DeclareUnicodeCharacter{2299}{\ensuremath\odot}% + \DeclareUnicodeCharacter{22A2}{\ensuremath\vdash}% + \DeclareUnicodeCharacter{22A3}{\ensuremath\dashv}% + \DeclareUnicodeCharacter{22A4}{\ensuremath\ptextop}% + \DeclareUnicodeCharacter{22A5}{\ensuremath\bot}% + \DeclareUnicodeCharacter{22A8}{\ensuremath\models}% + \DeclareUnicodeCharacter{22C0}{\ensuremath\bigwedge}% + \DeclareUnicodeCharacter{22C1}{\ensuremath\bigvee}% + \DeclareUnicodeCharacter{22C2}{\ensuremath\bigcap}% + \DeclareUnicodeCharacter{22C3}{\ensuremath\bigcup}% + \DeclareUnicodeCharacter{22C4}{\ensuremath\diamond}% + \DeclareUnicodeCharacter{22C5}{\ensuremath\cdot}% + \DeclareUnicodeCharacter{22C6}{\ensuremath\star}% + \DeclareUnicodeCharacter{22C8}{\ensuremath\bowtie}% + \DeclareUnicodeCharacter{2308}{\ensuremath\lceil}% + \DeclareUnicodeCharacter{2309}{\ensuremath\rceil}% + \DeclareUnicodeCharacter{230A}{\ensuremath\lfloor}% + \DeclareUnicodeCharacter{230B}{\ensuremath\rfloor}% + \DeclareUnicodeCharacter{2322}{\ensuremath\frown}% + \DeclareUnicodeCharacter{2323}{\ensuremath\smile}% + % + \DeclareUnicodeCharacter{25B3}{\ensuremath\triangle}% + \DeclareUnicodeCharacter{25B7}{\ensuremath\triangleright}% + \DeclareUnicodeCharacter{25BD}{\ensuremath\bigtriangledown}% + \DeclareUnicodeCharacter{25C1}{\ensuremath\triangleleft}% + \DeclareUnicodeCharacter{25C7}{\ensuremath\diamond}% + \DeclareUnicodeCharacter{2660}{\ensuremath\spadesuit}% + \DeclareUnicodeCharacter{2661}{\ensuremath\heartsuit}% + \DeclareUnicodeCharacter{2662}{\ensuremath\diamondsuit}% + \DeclareUnicodeCharacter{2663}{\ensuremath\clubsuit}% + \DeclareUnicodeCharacter{266D}{\ensuremath\flat}% + \DeclareUnicodeCharacter{266E}{\ensuremath\natural}% + \DeclareUnicodeCharacter{266F}{\ensuremath\sharp}% + \DeclareUnicodeCharacter{26AA}{\ensuremath\bigcirc}% + \DeclareUnicodeCharacter{27B9}{\ensuremath\rangle}% + \DeclareUnicodeCharacter{27C2}{\ensuremath\perp}% + \DeclareUnicodeCharacter{27E8}{\ensuremath\langle}% + \DeclareUnicodeCharacter{27F5}{\ensuremath\longleftarrow}% + \DeclareUnicodeCharacter{27F6}{\ensuremath\longrightarrow}% + \DeclareUnicodeCharacter{27F7}{\ensuremath\longleftrightarrow}% + \DeclareUnicodeCharacter{27FC}{\ensuremath\longmapsto}% + \DeclareUnicodeCharacter{29F5}{\ensuremath\setminus}% + \DeclareUnicodeCharacter{2A00}{\ensuremath\bigodot}% + \DeclareUnicodeCharacter{2A01}{\ensuremath\bigoplus}% + \DeclareUnicodeCharacter{2A02}{\ensuremath\bigotimes}% + \DeclareUnicodeCharacter{2A04}{\ensuremath\biguplus}% + \DeclareUnicodeCharacter{2A06}{\ensuremath\bigsqcup}% + \DeclareUnicodeCharacter{2A3F}{\ensuremath\amalg}% + \DeclareUnicodeCharacter{2AAF}{\ensuremath\preceq}% + \DeclareUnicodeCharacter{2AB0}{\ensuremath\succeq}% + % + \global\mathchardef\checkmark="1370% actually the square root sign + \DeclareUnicodeCharacter{2713}{\ensuremath\checkmark}% +}% end of \unicodechardefs + +% UTF-8 byte sequence (pdfTeX) definitions (replacing and @U command) +% It makes the setting that replace UTF-8 byte sequence. +\def\utfeightchardefs{% + \let\DeclareUnicodeCharacter\DeclareUnicodeCharacterUTFviii + \unicodechardefs +} + +% Whether the active definitions of non-ASCII characters expand to +% non-active tokens with the same character code. This is used to +% write characters literally, instead of using active definitions for +% printing the correct glyphs. +\newif\ifpassthroughchars +\passthroughcharsfalse + +% For native Unicode handling (XeTeX and LuaTeX), +% provide a definition macro to replace/pass-through a Unicode character +% +\def\DeclareUnicodeCharacterNative#1#2{% + \catcode"#1=\active + \def\dodeclareunicodecharacternative##1##2##3{% + \begingroup + \uccode`\~="##2\relax + \uppercase{\gdef~}{% + \ifpassthroughchars + ##1% + \else + ##3% + \fi + } + \endgroup + } + \begingroup + \uccode`\.="#1\relax + \uppercase{\def\UTFNativeTmp{.}}% + \expandafter\dodeclareunicodecharacternative\UTFNativeTmp{#1}{#2}% + \endgroup +} + +% Native Unicode handling (XeTeX and LuaTeX) character replacing definition. +% It activates the setting that replaces Unicode characters. +\def\nativeunicodechardefs{% + \let\DeclareUnicodeCharacter\DeclareUnicodeCharacterNative + \unicodechardefs +} + +% For native Unicode handling (XeTeX and LuaTeX), +% make the character token expand +% to the sequences given in \unicodechardefs for printing. +\def\DeclareUnicodeCharacterNativeAtU#1#2{% + \def\UTFAtUTmp{#2} + \expandafter\globallet\csname uni:#1\endcsname \UTFAtUTmp +} + +% @U command definitions for native Unicode handling (XeTeX and LuaTeX). +\def\nativeunicodechardefsatu{% + \let\DeclareUnicodeCharacter\DeclareUnicodeCharacterNativeAtU + \unicodechardefs +} + +% US-ASCII character definitions. +\def\asciichardefs{% nothing need be done + \relax +} + +% define all Unicode characters we know about, for the sake of @U. +\iftxinativeunicodecapable + \nativeunicodechardefsatu +\else + \utfeightchardefs +\fi + + +% 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 + \txipageheight = \vsize + % + \hsize = #2\relax + \outerhsize = \hsize + \advance\outerhsize by 0.5in + \txipagewidth = \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 + \else + \ifx\XeTeXrevision\thisisundefined + \special{papersize=#8,#7}% + \else + \pdfpageheight #7\relax + \pdfpagewidth #8\relax + % XeTeX does not have \pdfhorigin and \pdfvorigin. + \fi + \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 + \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 + \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 + \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 + \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 + \advance\dimen0 by 1in % reference point for DVI is 1 inch from top of page + % + \dimen2 = \hsize + \advance\dimen2 by \normaloffset + \advance\dimen2 by 1in % reference point is 1 inch from left edge of page + % + \internalpagesizes{#1}{\hsize}% + {\voffset}{\normaloffset}% + {\bindingoffset}{44pt}% + {\dimen0}{\dimen2}% +}} + +% Set default to letter. +% +\letterpaper + +% Default value of \hfuzz, for suppressing warnings about overfull hboxes. +\hfuzz = 1pt + + +\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} + +% Set catcodes for Texinfo file + +% Active characters for printing the wanted glyph. +% 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\hatchar=`\^ +\catcode`\^=\active \def\activehat{{\tt \hatchar}} \let^ = \activehat + +\catcode`\_=\active +\def_{\ifusingtt\normalunderscore\_} +\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em } +\let\realunder=_ + +\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 +\catcode`\-=\active \let-=\normaldash + + +% 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. +} + +% 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. + +% Print a typewriter backslash. For math mode, we can't simply use +% \backslashcurfont: 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). 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@ttbackslash{{@tt @ifmmode @mathchar29020 @else @backslashcurfont @fi}} +@let@backslashchar = @ttbackslash % @backslashchar{} is for user documents. + +% \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 `\'. +% +{@catcode`- = @active + @gdef@normalturnoffactive{% + @passthroughcharstrue + @let-=@normaldash + @let"=@normaldoublequote + @let$=@normaldollar %$ font-lock fix + @let+=@normalplus + @let<=@normalless + @let>=@normalgreater + @let^=@normalcaret + @let_=@normalunderscore + @let|=@normalverticalbar + @let~=@normaltilde + @let\=@ttbackslash + @markupsetuplqdefault + @markupsetuprqdefault + @unsepspaces + } +} + +% 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 @fixbackslash turn them back on. +@catcode`+=@other @catcode`@_=@other + +% \enablebackslashhack - allow file to begin `\input texinfo' +% +% 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. +% If the file did not have a `\input texinfo', then it is turned off after +% the first line; otherwise the first `\' in the file would cause an error. +% This is used on the very last line of this file, texinfo.tex. +% We also use @c to call @fixbackslash, in case ends of lines are hidden. +{ +@catcode`@^=7 +@catcode`@^^M=13@gdef@enablebackslashhack{% + @global@let\ = @eatinput% + @catcode`@^^M=13% + @def@c{@fixbackslash@c}% + % Definition for the newline at the end of this file. + @def ^^M{@let^^M@secondlinenl}% + % Definition for a newline in the main Texinfo file. + @gdef @secondlinenl{@fixbackslash}% + % In case the first line has a whole-line command on it + @let@originalparsearg@parsearg + @def@parsearg{@fixbackslash@originalparsearg} +}} + +{@catcode`@^=7 @catcode`@^^M=13% +@gdef@eatinput input texinfo#1^^M{@fixbackslash}} + +% Emergency active definition of newline, in case an active newline token +% appears by mistake. +{@catcode`@^=7 @catcode13=13% +@gdef@enableemergencynewline{% + @gdef^^M{% + @par% + %<warning: active newline>@par% +}}} + + +@gdef@fixbackslash{% + @ifx\@eatinput @let\ = @ttbackslash @fi + @catcode13=5 % regular end of line + @enableemergencynewline + @let@c=@texinfoc + @let@parsearg@originalparsearg + % Also turn back on active characters that might appear in the input + % file name, in case not using a pre-dumped format. + @catcode`+=@active + @catcode`@_=@active + % + % If texinfo.cnf is present on the system, read it. + % Useful for site-wide @afourpaper, etc. This macro, @fixbackslash, gets + % called at the beginning of every Texinfo file. Not opening texinfo.cnf + % directly in this file, texinfo.tex, makes it possible to make a format + % file for Texinfo. + % + @openin 1 texinfo.cnf + @ifeof 1 @else @input texinfo.cnf @fi + @closein 1 +} + + +% 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 'before-save-hook 'time-stamp) +@c page-delimiter: "^\\\\message\\|emacs-page" +@c time-stamp-start: "def\\\\texinfoversion{" +@c time-stamp-format: "%:y-%02m-%02d.%02H" +@c time-stamp-end: "}" +@c End: + +@c vim:sw=2: + +@enablebackslashhack diff --git a/macros/texinfo/texinfo/doc/texinfo.texi b/macros/texinfo/texinfo/doc/texinfo.texi new file mode 100644 index 0000000000..70567bb668 --- /dev/null +++ b/macros/texinfo/texinfo/doc/texinfo.texi @@ -0,0 +1,24217 @@ +\input texinfo.tex @c -*-texinfo-*- + +@c Everything between the start/end of header lines will be passed by +@c Emacs's {texinfo,makeinfo}-format region commands. See the `start of +@c header' node for more info. +@c %**start of header + +@c Automake requires this +@setfilename texinfo.info + +@c Automake automatically updates version.texi to @set VERSION and +@c @set UPDATED to appropriate values. +@include version.texi +@settitle GNU Texinfo @value{VERSION} + +@c Define a new index for command-line options. +@defcodeindex op + +@c Put everything except function (command, in this case) names in one +@c index (arbitrarily chosen to be the concept index). +@syncodeindex op cp +@syncodeindex vr cp +@syncodeindex pg cp + +@c finalout + +@comment %**end of header + +@copying +This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), +a documentation system that can produce both online information and a +printed manual from a single source using semantic markup. + +Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, +1998, 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009, +2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 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, with the Front-Cover Texts being ``A GNU Manual'', +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation +License''. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual. Buying copies from the FSF supports it in +developing GNU and promoting software freedom.'' +@end quotation +@end copying + +@dircategory Texinfo documentation system +@direntry +* Texinfo: (texinfo). The GNU documentation format. +* install-info: (texinfo)Invoking install-info. Update info/dir entries. +* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. +* pod2texi: (pod2texi)Invoking pod2texi. Translate Perl POD to Texinfo. +* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. +* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo. +* pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo. +* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. +@end direntry + +@c Set smallbook if printing in smallbook format so the example of the +@c smallbook font is actually written using smallbook; in bigbook, a kludge +@c is used for TeX output. Do this through the -t option to texi2dvi, +@c so this same source can be used for other paper sizes as well. +@c smallbook +@c set smallbook +@c @@clear smallbook + +@c If you like blank pages, add through texi2dvi -t. +@c setchapternewpage odd + +@set txiindexatsignignore +@set txiindexbackslashignore +@set txiindexlessthanignore +@set txiindexhyphenignore + + +@titlepage +@title Texinfo +@subtitle The GNU Documentation Format +@subtitle for Texinfo version @value{VERSION}, @value{UPDATED} + +@author Robert J. Chassell +@author Richard M. Stallman + +@c Include the Distribution inside the titlepage so +@c that headings are turned off. + +@page +@vskip 0pt plus 1filll +@insertcopying + +@sp 1 +Published by the Free Software Foundation @* +51 Franklin St, Fifth Floor @* +Boston, MA 02110-1301 @* +USA @* +ISBN 1-882114-67-1 @c for version 4.0, September 1999. +@c ISBN 1-882114-65-5 is for version 3.12, March 1998. +@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996. +@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995. + +@sp 1 +Cover art by Etienne Suvasa. +@end titlepage + + +@summarycontents +@contents + + +@ifnottex +@node Top +@top Texinfo + +This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), +a documentation system that can produce both online information and a +printed manual from a single source using semantic markup. + +@end ifnottex + +@ifinfo +The first part of this master menu lists the major nodes in this Info +document, including the @@-command and concept indices. The rest of +the menu lists all the lower-level nodes in the document. +@end ifinfo + + +@menu +* Copying Conditions:: Your rights. +* Overview:: Texinfo in brief. +* Writing a Texinfo File:: Format of a Texinfo source file. +* Beginning and Ending a File:: Beginning and end of a Texinfo file. +* Nodes:: Writing nodes, the basic unit of Texinfo. +* Chapter Structuring:: Creating chapters, sections, appendices, etc. +* Cross References:: Writing cross-references. +* Marking Text:: Marking words and phrases as code, + keyboard input, meta-syntactic + variables, and the like. +* Quotations and Examples:: Block quotations, examples, etc. +* Lists and Tables:: Itemized or numbered lists, and tables. +* Special Displays:: Floating figures and footnotes. +* Indices:: Creating indices. +* Insertions:: Inserting @@-signs, braces, etc. +* Breaks:: Forcing or preventing line and page breaks. +* Definition Commands:: Describing functions and the like uniformly. +* Internationalization:: Supporting languages other than English. +* Conditionals:: Specifying text for only some output cases. +* Defining New Texinfo Commands:: User-defined macros and aliases. +* Include Files:: How to incorporate other Texinfo files. +* Hardcopy:: Output for paper, with @TeX{}. +* Generic Translator @command{texi2any}:: @command{texi2any}, an all-purpose converter. +* Creating and Installing Info Files:: Details on Info output. +* Generating HTML:: Details on HTML output. +@c * texi2any Output Customization:: Fine tuning with initialization files. + +Appendices + +* @@-Command Details:: Details of the Texinfo @@-commands. +* Tips:: Hints on how to write a Texinfo document. +* Sample Texinfo Files:: Complete examples, including full texts. +* Texinfo Mode:: Using the GNU Emacs Texinfo mode. +* Headings:: How to write page headings and footings. +* Catching Mistakes:: How to find mistakes in formatting. +* Info Format Specification:: Technical details of the Info file format. +* GNU Free Documentation License:: Copying this manual. +* Command and Variable Index:: A menu containing commands and variables. +* General Index:: A menu covering many topics. + +@detailmenu + --- The Detailed Node Listing --- + +Overview of Texinfo + +* Reporting Bugs:: Submitting effective bug reports. +* Output Formats:: Overview of the supported output formats. +* Info Files:: What is an Info file? +* Printed Books:: Characteristics of a printed book or manual. +* Adding Output Formats:: Man pages and implementing new formats. +* History:: Acknowledgements, contributors and genesis. + +Writing a Texinfo File + +* Command Syntax:: @@-commands are used for formatting. +* Conventions:: General rules for writing a Texinfo file. +* Comments:: Writing comments and ignored text in general. +* Minimum:: What a Texinfo file must have. +* Short Sample:: A short sample Texinfo file. + +Beginning and Ending a Texinfo File + +* Sample Beginning:: A sample beginning for a Texinfo file. +* Texinfo File Header:: The first lines. +* Document Permissions:: Ensuring your manual is free. +* Titlepage & Copyright Page:: Creating the title and copyright pages. +* Contents:: How to create a table of contents. +* The Top Node:: Creating the `Top' node and master menu. +* Global Document Commands:: Affecting formatting throughout. +* Ending a File:: What is at the end of a Texinfo file? + +Texinfo File Header + +* First Line:: The first line of a Texinfo file. +* Start of Header:: Formatting a region requires this. +* @code{@@setfilename}:: Tell Info the name of the Info file. +* @code{@@settitle}:: Create a title for the printed work. +* End of Header:: Formatting a region requires this. + +Document Permissions + +* @code{@@copying}:: Declare the document's copying permissions. +* @code{@@insertcopying}:: Where to insert the permissions. + +Title and Copyright Pages + +* @code{@@titlepage}:: Create a title for the printed document. +* @code{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center}, + and @code{@@sp} commands. +* @code{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle}, + and @code{@@author} commands. +* Copyright:: How to write the copyright notice and + include copying permissions. +* Heading Generation:: Turn on page headings after the title and + copyright pages. + +The `Top' Node and Master Menu + +* Top Node Example:: +* Master Menu Parts:: + +Global Document Commands + +* @code{@@documentdescription}:: Document summary for the HTML output. +* @code{@@setchapternewpage}:: Start chapters on right-hand pages. +* @code{@@headings}:: An option for turning headings on and off + and double or single sided printing. +* @code{@@paragraphindent}:: Specify paragraph indentation. +* @code{@@firstparagraphindent}:: Suppressing first paragraph indentation. +* @code{@@exampleindent}:: Specify environment indentation. + +Nodes + +* Texinfo Document Structure:: How Texinfo manuals are usually arranged. +* Node Names:: How to choose node names. +* Writing a Node:: How to write an @code{@@node} line. +* Node Line Requirements:: Keep names unique. +* First Node:: How to write a `Top' node. +* @code{@@top} Command:: How to use the @code{@@top} command. +* Node Menu Illustration:: A diagram, and sample nodes and menus. +* @command{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers. +* Menus:: Listing subordinate nodes. + +Menus + +* Writing a Menu:: What is a menu? +* Menu Example:: Two and three part menu entries. +* Menu Location:: Menus go at the ends of nodes. +* Menu Parts:: A menu entry has three parts. +* Less Cluttered Menu Entry:: Two part menu entry. +* Other Info Files:: How to refer to a different Info file. + +Chapter Structuring + +* Tree Structuring:: A manual is like an upside down tree @dots{} +* Structuring Command Types:: How to divide a manual into parts. +* @code{@@chapter}:: Chapter structuring. +* @code{@@unnumbered @@appendix}:: +* @code{@@majorheading @@chapheading}:: +* @code{@@section}:: +* @code{@@unnumberedsec @@appendixsec @@heading}:: +* @code{@@subsection}:: +* @code{@@unnumberedsubsec @@appendixsubsec @@subheading}:: +* @code{@@subsubsection}:: Commands for the lowest level sections. +* @code{@@part}:: Collections of chapters. +* Raise/lower sections:: How to change commands' hierarchical level. + +Cross-references + +* References:: What cross-references are for. +* Cross Reference Commands:: A summary of the different commands. +* Cross Reference Parts:: A cross-reference has several parts. +* @code{@@xref}:: Begin a reference with `See' @dots{} +* Referring to a Manual as a Whole:: Refer to an entire manual. +* @code{@@ref}:: A reference for the last part of a sentence. +* @code{@@pxref}:: How to write a parenthetical cross-reference. +* @code{@@anchor}:: Defining arbitrary cross-reference targets +* @code{@@inforef}:: How to refer to an Info-only file. +* @code{@@url}:: How to refer to a uniform resource locator. +* @code{@@cite}:: How to refer to books not in the Info system. + +@code{@@xref} + +* One Argument:: @code{@@xref} with one argument. +* Two Arguments:: @code{@@xref} with two arguments. +* Three Arguments:: @code{@@xref} with three arguments. +* Four and Five Arguments:: @code{@@xref} with four and five arguments. + +@code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} + +* @code{@@url} Examples:: Examples of using all the forms of @code{@@url}. +* URL Line Breaking:: How lines are broken within @code{@@url} text. +* @code{@@url} PDF Output Format:: A special option to hide links in PDF output. +* PDF Colors:: Colorizing urls and other links in PDF output. + +Marking Text, Words and Phrases + +* Indicating:: How to indicate definitions, files, etc. +* Emphasis:: How to emphasize text. + +Indicating Definitions, Commands, etc. + +* Useful Highlighting:: Highlighting provides useful information. +* @code{@@code}:: Indicating program code. +* @code{@@kbd}:: Showing keyboard input. +* @code{@@key}:: Specifying keys. +* @code{@@samp}:: Indicating a literal sequence of characters. +* @code{@@verb}:: Indicating a verbatim sequence of characters. +* @code{@@var}:: Indicating metasyntactic variables. +* @code{@@env}:: Indicating environment variables. +* @code{@@file}:: Indicating file names. +* @code{@@command}:: Indicating command names. +* @code{@@option}:: Indicating option names. +* @code{@@dfn}:: Specifying definitions. +* @code{@@abbr}:: Indicating abbreviations. +* @code{@@acronym}:: Indicating acronyms. +* @code{@@indicateurl}:: Indicating an example url. +* @code{@@email}:: Indicating an electronic mail address. + +Emphasizing Text + +* @code{@@emph @@strong}:: How to emphasize text in Texinfo. +* Smallcaps:: How to use the small caps font. +* Fonts:: Various font commands for printed output. + +Quotations and Examples + +* Block Enclosing Commands:: Different constructs for different purposes. +* @code{@@quotation}:: Writing a quotation. +* @code{@@indentedblock}:: Block of text indented on left. +* @code{@@example}:: Writing an example in a fixed-width font. +* @code{@@verbatim}:: Writing a verbatim example. +* @code{@@verbatiminclude}:: Including a file verbatim. +* @code{@@lisp}:: Illustrating Lisp code. +* @code{@@small@dots{}}:: Examples in a smaller font. +* @code{@@display}:: Writing an example in the current font. +* @code{@@format}:: Writing an example without narrowed margins. +* @code{@@exdent}:: Undo indentation on a line. +* @code{@@flushleft @@flushright}:: Pushing text flush left or flush right. +* @code{@@raggedright}:: Avoiding justification on the right. +* @code{@@noindent}:: Preventing paragraph indentation. +* @code{@@indent}:: Forcing paragraph indentation. +* @code{@@cartouche}:: Drawing rounded rectangles around text. + +Lists and Tables + +* Introducing Lists:: Texinfo formats lists for you. +* @code{@@itemize}:: How to construct a simple list. +* @code{@@enumerate}:: How to construct a numbered list. +* Two-column Tables:: How to construct a two-column table. +* Multi-column Tables:: How to construct generalized tables. + +Making a Two-column Table + +* @code{@@table}:: How to construct a two-column table. +* @code{@@ftable @@vtable}:: Automatic indexing for two-column tables. +* @code{@@itemx}:: How to put more entries in the first column. + +@code{@@multitable}: Multi-column Tables + +* Multitable Column Widths:: Defining multitable column widths. +* Multitable Rows:: Defining multitable rows, with examples. + +Special Displays + +* Floats:: Figures, tables, and the like. +* Images:: Including graphics and images. +* Footnotes:: Writing footnotes. + +Floats + +* @code{@@float}:: Producing floating material. +* @code{@@caption @@shortcaption}:: Specifying descriptions for floats. +* @code{@@listoffloats}:: A table of contents for floats. + +Inserting Images + +* Image Syntax:: +* Image Scaling:: + +Footnotes + +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. + +Indices + +* Index Entries:: Choose different words for index entries. +* Predefined Indices:: Use different indices for different kinds + of entries. +* Indexing Commands:: How to make an index entry. +* Printing Indices & Menus:: How to print an index in hardcopy and + generate index menus in Info. +* Combining Indices:: How to combine indices. +* New Indices:: How to define your own indices. + +Combining Indices + +* @code{@@syncodeindex}:: How to merge two indices, using @code{@@code} + font for the merged-from index. +* @code{@@synindex}:: How to merge two indices, using the + roman font for the merged-from index. + +Special Insertions + +* Special Characters:: Inserting @@ @{@} , \ # & +* Inserting Quote Characters:: Inserting left and right quotes, in code. +* Inserting Space:: Inserting the right amount of whitespace. +* Inserting Accents:: Inserting accents and special characters. +* Inserting Quotation Marks:: Inserting quotation marks. +* Inserting Subscripts and Superscripts:: Inserting sub/superscripts. +* Inserting Math:: Formatting mathematical expressions. +* Glyphs for Text:: Inserting dots, bullets, currencies, etc. +* Glyphs for Programming:: Indicating results of evaluation, + expansion of macros, errors, etc. +* Inserting Unicode:: Inserting a Unicode character by code point. + +Special Characters: Inserting @@ @{@} , \ # & + +* Inserting an Atsign:: @code{@@@@}, @code{@@atchar@{@}}. +* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l rbracechar@{@}}. +* Inserting a Comma:: , and @code{@@comma@{@}}. +* Inserting a Backslash:: \ and @code{@@backslashchar@{@}}. +* Inserting a Hashsign:: # and @code{@@hashchar@{@}}. +* Inserting an Ampersand:: & and @code{@@ampchar@{@}}. + +Inserting Space + +* Multiple Spaces:: Inserting multiple spaces. +* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. +* Ending a Sentence:: Sometimes it does. +* @code{@@frenchspacing}:: Specifying end-of-sentence spacing. +* @code{@@dmn}:: Formatting a dimension. + +Glyphs for Text + +* @code{@@TeX @@LaTeX}:: The @TeX{} logos. +* @code{@@copyright}:: The copyright symbol (c in a circle). +* @code{@@registeredsymbol}:: The registered symbol (R in a circle). +* @code{@@dots}:: How to insert ellipses: @dots{} and @enddots{} +* @code{@@bullet}:: How to insert a bullet: @bullet{} +* @code{@@euro}:: How to insert the euro currency symbol. +* @code{@@pounds}:: How to insert the pounds currency symbol. +* @code{@@textdegree}:: How to insert the degrees symbol. +* @code{@@minus}:: How to insert a minus sign. +* @code{@@geq @@leq}:: How to insert greater/less-than-or-equal signs. + +Glyphs for Programming + +* Glyphs Summary:: +* @code{@@result}:: How to show the result of expression. +* @code{@@expansion}:: How to indicate an expansion. +* @code{@@print}:: How to indicate generated output. +* @code{@@error}:: How to indicate an error message. +* @code{@@equiv}:: How to indicate equivalence. +* @code{@@point}:: How to indicate the location of point. +* Click Sequences:: Inserting GUI usage sequences. + +Forcing and Preventing Breaks + +* Break Commands:: Summary of break-related commands. +* Line Breaks:: Forcing line breaks. +* @code{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points. +* @code{@@allowcodebreaks}:: Controlling line breaks within @@code text. +* @code{@@w}:: Preventing unwanted line breaks in text. +* @code{@@tie}:: Inserting an unbreakable but varying space. +* @code{@@sp}:: Inserting blank lines. +* @code{@@page}:: Forcing the start of a new page. +* @code{@@group}:: Preventing unwanted page breaks. +* @code{@@need}:: Another way to prevent unwanted page breaks. + +Definition Commands + +* Def Cmd Template:: Writing descriptions using definition commands. +* Def Cmd Continuation Lines:: Continuing the heading over source lines. +* Optional Arguments:: Handling optional and repeated arguments. +* @code{@@deffnx}:: Group two or more `first' lines. +* Def Cmds in Detail:: Reference for all the definition commands. +* Def Cmd Conventions:: Conventions for writing definitions. +* Sample Function Definition:: An example. + +The Definition Commands + +* Functions Commands:: Commands for functions and similar entities. +* Variables Commands:: Commands for variables and similar entities. +* Typed Functions:: Commands for functions in typed languages. +* Typed Variables:: Commands for variables in typed languages. +* Data Types:: The definition command for data types. +* Abstract Objects:: Commands for object-oriented programming. + +Object-Oriented Programming + +* Variables: Object-Oriented Variables. +* Methods: Object-Oriented Methods. + +Internationalization + +* @code{@@documentlanguage}:: Declaring the current language. +* @code{@@documentencoding}:: Declaring the input encoding. + +Conditionally Visible Text + +* Conditional Commands:: Text for a given format. +* Conditional Not Commands:: Text for any format other than a given one. +* Raw Formatter Commands:: Using raw formatter commands. +* Inline Conditionals:: Brace-delimited conditional text. +* @code{@@set @@clear @@value}:: Variable tests and substitutions. +* Testing for Texinfo Commands:: Testing if a Texinfo command is available. +* Conditional Nesting:: Using conditionals inside conditionals. + +Flags: @code{@@set}, @code{@@clear}, conditionals, and @code{@@value} + +* @code{@@set @@value}:: Expand a flag variable to a string. +* @code{@@ifset @@ifclear}:: Format a region if a flag is set. +* @code{@@inlineifset @@inlineifclear}:: Brace-delimited flag conditionals. +* @code{@@value} Example:: An easy way to update edition information. + +Defining New Texinfo Commands + +* Defining Macros:: Defining and undefining new commands. +* Invoking Macros:: Using a macro, once you've defined it. +* Macro Details:: Limitations of Texinfo macros. +* @code{@@alias}:: Command aliases. +* @code{@@definfoenclose}:: Customized highlighting. +* External Macro Processors:: @code{#line} directives. + +External Macro Processors: Line Directives + +* @samp{#line} Directive:: +* TeX: @samp{#line} and @TeX{}. +* Syntax: @samp{#line} Syntax Details. + +Include Files + +* Using Include Files:: How to use the @code{@@include} command. +* @code{texinfo-multiple-files-update}:: How to create and update nodes and + menus when using included files. +* Include Files Requirements:: @code{texinfo-multiple-files-update} needs. +* Sample Include File:: A sample outer file with included files + within it; and a sample included file. +* Include Files Evolution:: How use of the @code{@@include} command + has changed over time. + +Formatting and Printing Hardcopy + +* Use @TeX{}:: Use @TeX{} to format for hardcopy. +* Format with @command{texi2dvi}:: The simplest way to format. +* Format with @command{tex}/@command{texindex}:: Formatting with explicit shell commands. +* Print with @command{lpr}:: How to print. +* Within Emacs:: How to format and print from an Emacs shell. +* Texinfo Mode Printing:: How to format and print in Texinfo mode. +* Compile-Command:: How to print using Emacs's compile command. +* Requirements Summary:: @TeX{} formatting requirements summary. +* Preparing for @TeX{}:: What to do before you use @TeX{}. +* Overfull hboxes:: What are and what to do with overfull hboxes. +* @code{@@smallbook}:: How to print small format books and manuals. +* A4 Paper:: How to print on A4 or A5 paper. +* @code{@@pagesizes}:: How to print with customized page sizes. +* Magnification:: How to print scaled up output. +* PDF Output:: Portable Document Format output. +* Obtaining @TeX{}:: How to obtain @TeX{}. + +Format with @command{tex}/@command{texindex} + +* Formatting Partial Documents:: +* Details of @command{texindex}:: + +@command{texi2any}: The Generic Translator for Texinfo + +* Reference Implementation:: @command{texi2any}: the reference implementation. +* Invoking @command{texi2any}:: Running the translator from a shell. +* @command{texi2any} Environment Variables:: +* @command{texi2any} Printed Output:: Calling @command{texi2dvi}. +* Pointer Validation:: How to check that pointers point somewhere. +* Customization Variables:: Configuring @command{texi2any}. +* Internationalization of Document Strings:: Translating program-inserted text. +* Invoking @command{pod2texi}:: Translating Perl pod to Texinfo. +* @command{texi2html}:: An ancestor of @command{texi2any}. + +Customization Variables + +* Commands: Customization Variables for @@-Commands. +* Options: Customization Variables and Options. +* HTML: HTML Customization Variables. +* Other: Other Customization Variables. + +Creating and Installing Info Files + +* Creating an Info File:: +* Installing an Info File:: + +Creating an Info File + +* @command{makeinfo} Advantages:: @command{makeinfo} provides better error checking. +* @code{makeinfo} in Emacs:: How to run @code{makeinfo} from Emacs. +* @code{texinfo-format} commands:: Two Info formatting commands written + in Emacs Lisp are an alternative + to @code{makeinfo}. +* Batch Formatting:: How to format for Info in Emacs batch mode. +* Tag and Split Files:: How tagged and split files help Info + to run better. + +Installing an Info File + +* Directory File:: The top level menu for all Info files. +* New Info File:: Listing a new Info file. +* Other Info Directories:: How to specify Info files that are + located in other directories. +* Installing Dir Entries:: How to specify what menu entry to add + to the Info directory. +* Invoking @command{install-info}:: @code{install-info} options. + +Generating HTML + +* HTML Translation:: Details of the HTML output. +* HTML Splitting:: How HTML output is split. +* HTML CSS:: Influencing HTML output with Cascading Style Sheets. +* HTML Xref:: Cross-references in HTML output. + +HTML Cross-references + +* Link Basics: HTML Xref Link Basics. +* Node Expansion: HTML Xref Node Name Expansion. +* Command Expansion: HTML Xref Command Expansion. +* 8-bit Expansion: HTML Xref 8-bit Character Expansion. +* Mismatch: HTML Xref Mismatch. +* Configuration: HTML Xref Configuration. htmlxref.cnf. +* Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf. + +Sample Texinfo Files + +* Short Sample Texinfo File:: +* GNU Sample Texts:: +* Verbatim Copying License:: +* All-permissive Copying License:: + +Using Texinfo Mode + +* Texinfo Mode Overview:: How Texinfo mode can help you. +* Emacs Editing:: Texinfo mode adds to GNU Emacs' general + purpose editing features. +* Inserting:: How to insert frequently used @@-commands. +* Showing the Structure:: How to show the structure of a file. +* Updating Nodes and Menus:: How to update or create new nodes and menus. +* Info Formatting:: How to format for Info. +* Printing:: How to format and print part or all of a file. +* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. + +Updating Nodes and Menus + +* Updating Commands:: Five major updating commands. +* Updating Requirements:: How to structure a Texinfo file for + using the updating command. +* Other Updating Commands:: How to indent descriptions, insert + missing nodes lines, and update + nodes in sequence. + +Page Headings + +* Headings Introduced:: Conventions for using page headings. +* Heading Format:: Standard page heading formats. +* Heading Choice:: How to specify the type of page heading. +* Custom Headings:: How to create your own headings and footings. + +Catching Mistakes + +* @command{makeinfo} Preferred:: @code{makeinfo} finds errors. +* Debugging with Info:: How to catch errors with Info formatting. +* Debugging with @TeX{}:: How to catch errors with @TeX{} formatting. +* Using @code{texinfo-show-structure}:: How to use @code{texinfo-show-structure}. +* Using @code{occur}:: How to list all lines containing a pattern. +* Running @code{Info-validate}:: How to find badly referenced nodes. + +Finding Badly Referenced Nodes + +* Using @code{Info-validate}:: How to run @code{Info-validate}. +* Unsplit:: How to create an unsplit file. +* Tagifying:: How to tagify a file. +* Splitting:: How to split a file manually. + +Info Format Specification + +* General: Info Format General Layout. +* Text: Info Format Text Constructs. + +Info Format General Layout + +* Whole: Info Format Whole Manual. Split vs.@: nonsplit manuals. +* Preamble: Info Format Preamble. +* Indirect: Info Format Indirect Table. +* Tag table: Info Format Tag Table. +* Local variables: Info Format Local Variables. +* Regular nodes: Info Format Regular Nodes. + +Info Format Text Constructs + +* Info Format Menu:: +* Info Format Image:: +* Info Format Printindex:: +* Info Format Cross Reference:: + +@end detailmenu +@end menu + +@c Reward readers for getting to the end of the menu :). +@c Contributed by Arnold Robbins. +@quotation +Documentation is like sex: when it is good, it is very, very good; and +when it is bad, it is better than nothing. +---Dick Brandon +@end quotation + + +@node Copying Conditions +@unnumbered Texinfo Copying Conditions +@cindex Copying conditions +@cindex Conditions for copying Texinfo +@cindex Free software +@cindex Libre software + +GNU Texinfo is @dfn{free software}; this means that everyone is free +to use it and free to redistribute it on certain conditions. Texinfo +is not in the public domain; it is copyrighted and there are +restrictions on its distribution, but these restrictions are designed +to permit everything that a good cooperating citizen would want to do. +What is not allowed is to try to prevent others from further sharing +any version of Texinfo that they might get from you. + +Specifically, we want to make sure that you have the right to give away +copies of the programs that relate to Texinfo, that you receive source +code or else can get it if you want it, that you can change these +programs or use pieces of them in new free programs, and that you know +you can do these things. + +To make sure that everyone has such rights, we have to forbid you to +deprive anyone else of these rights. For example, if you distribute +copies of the Texinfo related programs, you must give the recipients all +the rights that you have. You must make sure that they, too, receive or +can get the source code. And you must tell them their rights. + +Also, for our own protection, we must make certain that everyone finds +out that there is no warranty for the programs that relate to Texinfo. +If these programs are modified by someone else and passed on, we want +their recipients to know that what they have is not what we distributed, +so that any problems introduced by others will not reflect on our +reputation. + +The precise conditions of the licenses for the programs currently +being distributed that relate to Texinfo are found in the General +Public Licenses that accompany them. This manual is covered by the +GNU Free Documentation License (@pxref{GNU Free Documentation +License}). + + +@node Overview +@chapter Overview of Texinfo +@cindex Overview of Texinfo +@cindex Texinfo overview +@cindex Using Texinfo in general +@cindex Texinfo, introduction to +@cindex Introduction to Texinfo +@anchor{Using Texinfo} @c merged node + +@dfn{Texinfo} is a documentation system that uses a single source file +to produce both online information and printed output. This means +that instead of writing several different documents, one for each output +format, you need only write one document. + +Using Texinfo, you can create a printed document (via the @TeX{} +typesetting system) in PDF or PostScript format, including chapters, +sections, cross-references, and indices. From the same Texinfo source +file, you can create an HTML output file suitable for use with a web +browser, you can create an Info file with special features to make +browsing documentation easy, and also create a Docbook file or a +transliteration to XML format. + +@cindex Source file format +@cindex Semantic markup +A Texinfo source file is a plain text file containing text interspersed +with @dfn{@@-commands} (words preceded by an @samp{@@}) that tell the +Texinfo processors what to do. Texinfo's markup commands are almost +entirely @dfn{semantic}; that is, they specify the intended meaning +of text in the document, rather than physical formatting instructions. +You can edit a Texinfo file with any text editor, but it is especially +convenient to use GNU Emacs since that editor has a special mode, +called Texinfo mode, that provides various Texinfo-related features. +(@xref{Texinfo Mode}.) + +@cindex Limited scope of Texinfo +Texinfo was devised specifically for the purpose of writing software +documentation and manuals. If you want to write a good manual for +your program, Texinfo has many features which we hope will make your +job easier. However, it provides almost no commands for controlling +the final formatting. Texinfo is not intended to be a general-purpose +formatting program, so if you need to lay out a newspaper, devise a +glossy magazine ad, or follow the exact formatting requirements of +a publishing house, Texinfo may not be the simplest tool. + +@cindex Spelling of Texinfo +@cindex Pronunciation of Texinfo +Spell ``Texinfo'' with a capital ``T'' and the other letters in +lowercase. The first syllable of ``Texinfo'' is pronounced like +``speck'', not ``hex''. This odd pronunciation is derived from the +pronunciation of @TeX{}. Pronounce @TeX{} as if the @samp{X} were +the last sound in the name `Bach'. In the word @TeX{}, the @samp{X} +is, rather than the English letter ``ex'', actually the Greek letter +``chi''. + +Texinfo is the official documentation format of the GNU project. +More information, including manuals for GNU packages, is available +at the @uref{http://www.gnu.org/doc/, GNU documentation web page}. + +@menu +* Reporting Bugs:: Submitting effective bug reports. +* Output Formats:: Overview of the supported output formats. +* Info Files:: What is an Info file? +* Printed Books:: Characteristics of a printed book or manual. +* Adding Output Formats:: Man pages and implementing new formats. +* History:: Acknowledgements, contributors and genesis. +@end menu + + +@node Reporting Bugs +@section Reporting Bugs + +@cindex Bugs, reporting +@cindex Suggestions for Texinfo, making +@cindex Reporting bugs +We welcome bug reports and suggestions for any aspect of the Texinfo +system: programs, documentation, installation, etc. Please email them +to @email{bug-texinfo@@gnu.org}. You can get the latest version of +Texinfo via its home page, @uref{http://www.gnu.org/software/texinfo}. + +@cindex Checklist for bug reports +For bug reports, please include enough information for the maintainers +to reproduce the problem. Generally speaking, that means: + +@itemize @bullet +@item The version number of Texinfo and the program(s) or manual(s) involved. +@item The contents of any input files necessary to reproduce the bug. +@item Precisely how you ran any program(s) involved. +@item A description of the problem and samples of any erroneous output. +@item Hardware and operating system names and versions. +@item Anything else that you think would be helpful. +@end itemize + +When in doubt whether something is needed or not, include it. It's +better to include too much than to leave out something important. + +It is critical to send an actual input file that reproduces the +problem. What's not critical is to ``narrow down'' the example to the +smallest possible input---the actual input with which you discovered +the bug will suffice. (Of course, if you do do experiments, the +smaller the input file, the better.) + +@cindex Patches, contributing +Patches are most welcome; if possible, please make them with +@samp{@w{diff -c}} (@pxref{Top,,, diffutils, Comparing and Merging +Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,, +emacs, The GNU Emacs Manual}), and follow the existing coding style. + + +@node Output Formats +@section Output Formats +@cindex Output formats +@cindex Back-end output formats + +Here is a brief overview of the output formats currently supported by +Texinfo. + +@table @asis +@item Info +@cindex Info output, overview +(Generated via @command{makeinfo}.) Info format is mostly a plain +text transliteration of the Texinfo source. It adds a few control +characters to provide navigational information for cross-references, +indices, and so on. The Emacs Info subsystem (@pxref{Top,,, info, +Info}), and the standalone @command{info} program (@pxref{Top,,, +info-stnd, GNU Info}), among others, can read these files. @xref{Info +Files}, and @ref{Creating and Installing Info Files}. + +@item Plain text +@cindex Plain text output, overview +(Generated via @command{makeinfo --plaintext}.) This is almost the +same as Info output with the navigational control characters are +omitted. + +@item HTML +@cindex HTML output, overview +@cindex W3 consortium +@cindex Mozilla +@cindex Lynx +@cindex Emacs-W3 +(Generated via @command{makeinfo --html}.) HTML, standing for Hyper +Text Markup Language, has become the most commonly used language for +writing documents on the World Wide Web. Web browsers, such as +Mozilla, Lynx, and Emacs-W3, can render this language online. There +are many versions of HTML, both different standards and +browser-specific variations. @command{makeinfo} tries to use a subset +of the language that can be interpreted by any common browser, +intentionally not using many newer or less widely-supported tags. +Although the native output is thus rather plain, it can be customized +at various levels, if desired. For details of the HTML language and +much related information, see @uref{http://www.w3.org/MarkUp/}. +@xref{Generating HTML}. + +@item DVI +@cindex DVI output, overview +@pindex dvips +@pindex xdvi +(Generated via @command{texi2dvi}.) The DeVIce Independent binary +format is output by the @TeX{} typesetting program +(@uref{http://tug.org}). This is then read by a DVI `driver', which +knows the actual device-specific commands that can be viewed or +printed, notably Dvips for translation to PostScript (@pxref{Top,,, +dvips, Dvips}) and Xdvi for viewing on an X display +(@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}. +(Be aware that the Texinfo language is very different from and much +stricter than @TeX{}'s usual languages: plain @TeX{}, @LaTeX{}, +Con@TeX{}t, etc.) + +@item PostScript +@cindex PostScript output, overview +(Generated via @command{texi2dvi --ps}.) PostScript is a page +description language that became widely used around 1985 and is still +used today. @uref{http://en.wikipedia.org/wiki/PostScript} gives a +basic description and more preferences. By default, Texinfo uses the +@command{dvips} program to convert @TeX{}'s DVI output to PostScript. +@xref{Top,,, dvips, Dvips}. + +@item PDF +@cindex PDF output, overview +@cindex Beebe, Nelson +(Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This +format was developed by Adobe Systems for portable document +interchange, based on their previous PostScript language. It can +represent the exact appearance of a document, including fonts and +graphics, and supporting arbitrary scaling. It is intended to be +platform-independent and easily viewable, among other design goals; +@uref{http://en.wikipedia.org/wiki/Portable_Document_Format} and +@uref{http://tug.org/TUGboat/tb22-3/tb72beebe-pdf.pdf} have some +background. By default, Texinfo uses the @command{pdftex} program, an +extension of @TeX{}, to output PDF; see +@uref{http://tug.org/applications/pdftex}. @xref{PDF Output}. + +@item Docbook +@cindex Docbook output, overview +@cindex XML Docbook output, overview +(Generated via @command{makeinfo --docbook}.) This is an XML-based +format developed some years ago, primarily for technical +documentation. It therefore bears some resemblance, in broad +outline, to Texinfo. See @uref{http://www.docbook.org}. Various +converters from Docbook @emph{to} Texinfo have also been developed; +see the Texinfo web pages. + +@item XML +@cindex XML Texinfo output, overview +@cindex Texinfo XML output, overview +@cindex DTD, for Texinfo XML +@pindex texinfo.dtd +@pindex txixml2texi +(Generated via @command{makeinfo --xml}.) XML is a generic syntax +specification usable for any sort of content (a reference is at +@uref{http://www.w3.org/XML}). The @command{makeinfo} XML output, +unlike all the other output formats, is a transliteration of the +Texinfo source rather than processed output. That is, it translates +the Texinfo markup commands into XML syntax, for further processing by +XML tools. The XML contains enough information to recreate the +original content, except for syntactic constructs such as Texinfo +macros and conditionals. The Texinfo source distribution includes a +utility script @file{txixml2texi} to do that backward transformation. + +The details of the output syntax are defined in an XML DTD as usual, +which is contained in a file @file{texinfo.dtd} included in the +Texinfo source distribution and available via the Texinfo web pages. +Texinfo XML files, and XML files in general, cannot be viewed in +typical web browsers; they won't follow the DTD reference and as a +result will simply report a (misleading) syntax error. +@end table + + +@node Info Files +@section Info Files +@cindex Info files + +As mentioned above, Info format is mostly a plain text transliteration +of the Texinfo source, with the addition of a few control characters +to separate nodes and provide navigational information, so that +Info-reading programs can operate on it. + +Info files are nearly always created by processing a Texinfo source +document. @command{makeinfo}, also known as @command{texi2any}, is +the principal command that converts a Texinfo file into an Info file; +@pxref{Generic Translator @command{texi2any}}. + +Generally, you enter an Info file through a node that by convention is +named `Top'. This node normally contains just a brief summary of the +file's purpose, and a large menu through which the rest of the file is +reached. From this node, you can either traverse the file +systematically by going from node to node, or you can go to a specific +node listed in the main menu, or you can search the index menus and then +go directly to the node that has the information you want. Alternatively, +with the standalone Info program, you can specify specific menu items on +the command line (@pxref{Top,,, info, Info}). + +If you want to read through an Info file in sequence, as if it were a +printed manual, you can hit @key{SPC} repeatedly, or you get the whole +file with the advanced Info command @kbd{g *}. (@xref{Advanced,, +Advanced Info commands, info, Info}.) + +The @file{dir} file in the @file{info} directory serves as the +departure point for the whole Info system. From it, you can reach the +`Top' nodes of each of the documents in a complete Info system. + +@cindex URI syntax for Info +If you wish to refer to an Info file via a URI, you can use the +(unofficial) syntax exemplified by the following. This works with +Emacs/W3, for example: +@example +info:emacs#Dissociated%20Press +info:///usr/info/emacs#Dissociated%20Press +info://localhost/usr/info/emacs#Dissociated%20Press +@end example + +The @command{info} program itself does not follow URIs of any kind. + + +@node Printed Books +@section Printed Books +@cindex Printed book and manual characteristics +@cindex Manual characteristics, printed +@cindex Book characteristics, printed +@cindex Texinfo printed book characteristics +@cindex Characteristics, printed books or manuals + +@cindex Knuth, Donald +A Texinfo file can be formatted and typeset as a printed book or +manual. To do this, you need @TeX{}, a sophisticated typesetting +program written by Donald Knuth of Stanford University. + +A Texinfo-based book is similar to any other typeset, printed work: it +can have a title page, copyright page, table of contents, and preface, +as well as chapters, numbered or unnumbered sections and subsections, +page headers, cross-references, footnotes, and indices. + +@TeX{} is a general purpose typesetting program. Texinfo provides a +file @file{texinfo.tex} that contains information (definitions or +@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. +(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands +to @TeX{} commands, which @TeX{} can then process to create the typeset +document.) @file{texinfo.tex} contains the specifications for printing +a document. You can get the latest version of @file{texinfo.tex} from +the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}. + +In the United States, documents are most often printed on 8.5 inch by +11 inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. +But you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by +235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper +(@code{@@afourpaper}, @code{@@afivepaper}). +@xref{@code{@@smallbook}}, and @ref{A4 Paper}. + +@cindex Literate programming +@TeX{} is freely distributable. It is written in a superset of Pascal +for literate programming called WEB and can be compiled either in +Pascal or (by using a conversion program that comes with the @TeX{} +distribution) in C. + +@TeX{} is very powerful and has a great many features. Because a +Texinfo file must be able to present information both on a +character-only terminal in Info form and in a typeset book, the +formatting commands that Texinfo supports are necessarily limited. + +@xref{Obtaining @TeX{}}, for information on acquiring @TeX{}. It is +not part of the Texinfo distribution. + + +@node Adding Output Formats +@section Adding Output Formats +@cindex Additional output formats + +The output formats in the previous sections handle a wide variety of +usage, but of course there is always room for more. + +@cindex Output formats, supporting more +@cindex SGML-tools output format +If you are a programmer and would like to contribute to the GNU +project by implementing additional output formats for Texinfo, that +would be excellent. The way to do this that would be most useful is +to write a new back-end for @command{texi2any}, our reference +implementation of a Texinfo parser; it creates a tree representation +of the Texinfo input that you can use for the conversion. The +documentation in the source file +@file{tp/Texinfo/Convert/Converter.pm} is a good place to start. +@xref{Generic Translator @command{texi2any}}. + +Another viable approach is use the Texinfo XML output from +@command{texi2any} as your input. This XML is an essentially complete +representation of the input, but without the Texinfo syntax and option +peculiarities, as described above. + +@cindex Texinfo parsers, discouraging more +If you still cannot resist the temptation of writing a new program +that reads Texinfo source directly, let us give some more caveats: +please do not underestimate the amount of work required. Texinfo is +by no means a simple language to parse correctly, and remains under +development, so you would be committing to an ongoing task. You +are advised to check that the tests of the language that come with +@command{texi2any} give correct results with your new program. + +@cindex Man page output, not supported +From time to time, proposals are made to generate traditional Unix man +pages from Texinfo source. However, because man pages have a strict +conventional format, creating a good man page requires a completely +different source from that needed for the typical Texinfo applications +of writing a good user tutorial and/or a good reference manual. This +makes generating man pages incompatible with the Texinfo design +goal of not having to document the same information in different +ways for different output formats. You might as well write the man +page directly. + +@pindex help2man +@cindex O'Dea, Brendan +As an alternative way to support man pages, you may find the program +@command{help2man} to be useful. It generates a traditional man page +from the @samp{--help} output of a program. In fact, the man pages +for the programs in the Texinfo distribution are generated with this. +It is GNU software written by Brendan O'Dea, available from +@uref{http://www.gnu.org/software/help2man}. + + + +@node History +@section History + +@cindex Stallman, Richard M. +@cindex Chassell, Robert J. +@cindex Fox, Brian +@cindex Berry, Karl +Richard M. Stallman invented the Texinfo format, wrote the initial +processors, and created Edition 1.0 of this manual. Robert@tie{}J. +Chassell greatly revised and extended the manual, starting with +Edition 1.1. Brian Fox was responsible for the standalone Texinfo +distribution until version 3.8, and originally wrote the standalone +@command{makeinfo} and @command{info} programs. Karl Berry has +continued maintenance since Texinfo 3.8 (manual edition 2.22). + +@cindex Pinard, Fran@,{c}ois +@cindex Schwab, Andreas +@cindex Weinberg, Zack +@cindex Weisshaus, Melissa +@cindex Zaretskii, Eli +@cindex Zuhn, David D. +Our thanks go out to all who helped improve this work, particularly +the indefatigable Eli Zaretskii and Andreas Schwab, who have provided +patches beyond counting. Fran@,{c}ois Pinard and David@tie{}D. Zuhn, +tirelessly recorded and reported mistakes and obscurities. Zack +Weinberg did the impossible by implementing the macro syntax in +@file{texinfo.tex}. Thanks to Melissa Weisshaus for her frequent +reviews of nearly similar editions. Dozens of others have contributed +patches and suggestions, they are gratefully acknowledged in the +@file{ChangeLog} file. Our mistakes are our own. + +@cindex History of Texinfo +@cindex Texinfo history +@subheading Beginnings + +@cindex Scribe +@cindex Reid, Brian +In the 1970's at CMU, Brian Reid developed a program and format named +Scribe to mark up documents for printing. It used the @code{@@} +character to introduce commands, as Texinfo does. Much more +consequentially, it strove to describe document contents rather than +formatting, an idea wholeheartedly adopted by Texinfo. + +@cindex Bolio +@cindex Bo@TeX{} +Meanwhile, people at MIT developed another, not too dissimilar format +called Bolio. This then was converted to using @TeX{} as its typesetting +language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been +0.02 on October 31, 1984. + +Bo@TeX{} could only be used as a markup language for documents to be +printed, not for online documents. Richard Stallman (RMS) worked on +both Bolio and Bo@TeX{}. He also developed a nifty on-line help format +called Info, and then combined Bo@TeX{} and Info to create Texinfo, a +mark up language for text that is intended to be read both online and +as printed hard copy. + +Moving forward, the original translator to create Info was written +(primarily by RMS and Bob Chassell) in Emacs Lisp, namely the +@code{texinfo-format-buffer} and other functions. In the early 1990s, +Brian Fox reimplemented the conversion program in C, now called +@command{makeinfo}. + +@subheading Reimplementing in Perl + +@cindex Cons, Lionel +@cindex Dumas, Patrice +In 2012, the C @command{makeinfo} was itself replaced by a Perl +implementation generically called @command{texi2any}. This version +supports the same level of output customization as +@command{texi2html}, an independent program originally written by +Lionel Cons, later with substantial work by many others. The many +additional features needed to make @command{texi2html} a replacement +for @command{makeinfo} were implemented by Patrice Dumas. The first +never-released version of @command{texi2any} was based on the +@command{texi2html} code. That implementation, however, was abandoned +in favor of the current program, which parses the Texinfo input into a +tree for processing. It still supports nearly all the features of +@command{texi2html}. + +The new Perl program is much slower than the old C program. We hope +the speed gap will close in the future, but it may not ever be +entirely comparable. So why did we switch? In short, we intend and +hope that the present program will be much easier than the previous C +implementation of @command{makeinfo} to extend to different output +styles, back-end output formats, and all other customizations. +In more detail: + +@itemize @bullet +@item HTML customization. Many GNU and other free software packages +had been happily using the HTML customization features in +@command{texi2html} for years. Thus, in effect two independent +implementations of the Texinfo language had developed, and keeping +them in sync was not simple. Adding the HTML customization possible +in @command{texi2html} to a C program would have been an +enormous effort. + +@item Unicode, and multilingual support generally, especially of east +Asian languages. Although of course it's perfectly plausible to write +such support in C, in the particular case of @command{makeinfo}, it +would have been tantamount to rewriting the entire program. In Perl, +much of that comes essentially for free. + +@item Additional back-ends. The @command{makeinfo} code had become +convoluted to the point where adding a new back-end was quite complex, +requiring complex interactions with existing back-ends. In contrast, +our Perl implementation provides a clean tree-based representation for +all back-ends to work from. People have requested numerous different +back-ends (@LaTeX{}, the latest (X)HTML, @dots{}), and they will now +be much more feasible to implement. Which leads to the last item: + +@item Making contributions easier. In general, due to the cleaner +structure, the Perl program should be considerably easier than the C +for anyone to read and contribute to, with the resulting obvious +benefits. +@end itemize + +@xref{Reference Implementation}, for more on the rationale for and +role of @command{texi2any}. + + +@node Writing a Texinfo File +@chapter Writing a Texinfo File + +This chapter describes Texinfo syntax and what is required in a Texinfo +file, and gives a short sample file. + +@menu +* Conventions:: General rules for writing a Texinfo file. +* Comments:: Writing comments and ignored text in general. +* Minimum:: What a Texinfo file must have. +* Short Sample:: A short sample Texinfo file. +@end menu + + +@node Conventions +@section General Syntactic Conventions +@cindex General syntactic conventions +@cindex Syntactic conventions +@cindex Conventions, syntactic +@cindex Characters, basic input +@anchor{Formatting Commands} @c old name + +This section describes the general conventions used in all Texinfo documents. + +@itemize @bullet +@item +@cindex Source files, characters used +All printable ASCII characters except @samp{@@}, @samp{@{} and +@samp{@}} can appear in a Texinfo file and stand for themselves. +@samp{@@} is the escape character which introduces commands, while +@samp{@{} and @samp{@}} are used to surround arguments to certain +commands. To put one of these special characters into the document, put +an @samp{@@} character in front of it, like this: @samp{@@@@}, +@samp{@@@{}, and @samp{@@@}}. + +@item +@cindex @@-commands +@cindex Formatting commands +In a Texinfo file, the commands you write to describe the contents of +the manual are preceded by an @samp{@@} character; they are called +@dfn{@@-commands}. (The @samp{@@} in Texinfo has the same meaning that +@samp{\} has in plain @TeX{}.) + +@cindex Braces, when to use +Depending on what they do or what arguments@footnote{The word +@dfn{argument} comes from the way it is used in mathematics and does not +refer to a dispute between two people; it refers to the information +presented to the command. According to the @cite{Oxford English +Dictionary}, the word derives from the Latin for @dfn{to make clear, +prove}; thus it came to mean `the evidence offered as proof', which is +to say, `the information offered', which led to its mathematical +meaning. In its other thread of derivation, the word came to mean `to +assert in a manner against which others may make counter assertions', +which led to the meaning of `argument' as a dispute.} they take, you +need to write @@-commands on lines of their own, or as part of +sentences. As a general rule, a command requires braces if it mingles +among other text; but it does not need braces if it is on a line of its +own. For more details of Texinfo command syntax, see @ref{Command +Syntax}. + + +@item +Whitespace following an @@-command name is optional and (usually) +ignored if present. The exceptions are contexts when whitespace is +significant, e.g., an @code{@@example} environment. + + +@item +Texinfo supports the usual quotation marks used in English and in +other languages; see @ref{Inserting Quotation Marks}. + +@item +@cindex Multiple dashes in source +@cindex Dashes in source +@cindex Hyphens in source, two or three in a row +@cindex Em dash, producing +@cindex En dash, producing +Use three hyphens in a row, @samp{---}, to produce a long dash---like +this (called an @dfn{em dash}), used for punctuation in sentences. +Use two hyphens, @samp{--}, to produce a medium dash (called an +@dfn{en dash}), used primarily for numeric ranges, as in ``June +25--26''. Use a single hyphen, @samp{-}, to produce a standard hyphen +used in compound words. For display on the screen, Info reduces three +hyphens to two and two hyphens to one (not transitively!). Of course, +any number of hyphens in the source remain as they are in literal +contexts, such as @code{@@code} and @code{@@example}. + +@item +@cindex Form feed characters +@cindex @kbd{CTRL-l} +Form feed (@kbd{CTRL-l}) characters in the input are handled as +follows: + +@table @asis +@item PDF/DVI +In normal text, treated as ending any open paragraph; essentially +ignored between paragraphs. + +@item Info +Output as-is between paragraphs (their most common use); in other +contexts, they may be treated as regular spaces (and thus consolidated +with surrounding whitespace). + +@item HTML +Written as a numeric entity except contexts where spaces are ignored; +for example, in @samp{@@footnote@{ ^L foo@}}, the form feed is +ignored. + +@item XML +Keep them everywhere; in attributes, escaped as @samp{\f}; also, +@samp{\} is escaped as @samp{\\} and newline as @samp{\n}. + +@item Docbook +Completely removed, as they are not allowed. +@end table + +As you can see, because of these differing requirements of the output +formats, it's not possible to use form feeds completely portably. + +@item +@cindex Tabs; don't use! +@strong{Caution:} Last, do not use tab characters in a Texinfo file! +(Except perhaps in verbatim modes.) @TeX{} uses variable-width fonts, +which means that it is impractical at best to define a tab to work in +all circumstances. Consequently, @TeX{} treats tabs like single +spaces, and that is not what they look like in the source. +Furthermore, @code{makeinfo} does nothing special with tabs, and thus +a tab character in your input file will usually have a different +appearance in the output. + +@noindent +To avoid this problem, Texinfo mode in GNU Emacs inserts +multiple spaces when you press the @key{TAB} key. Also, you can run +@code{untabify} in Emacs to convert tabs in a region to multiple +spaces, or use the @code{unexpand} command from the shell. +@end itemize + + +@node Comments +@section Comments + +@cindex Comments +@findex comment +@findex c + +You can write comments in a Texinfo file by using the @code{@@comment} +command, which may be abbreviated to @code{@@c}. Such comments are +for a person looking at the Texinfo source file. All the text on a +line that follows either @code{@@comment} or @code{@@c} is a comment; +the rest of the line does not appear in the visible output. (To be +precise, the character after the @code{@@c} or @code{@@comment} must +be something other than a dash or alphanumeric, or it will be taken as +part of the command.) + +Often, you can write the @code{@@comment} or @code{@@c} in the middle +of a line, and only the text that follows after the @code{@@comment} +or @code{@@c} command does not appear; but some commands, such as +@code{@@settitle}, work on a whole line. You cannot use @code{@@comment} +or @code{@@c} within a line beginning with such a command. + +@findex DEL @r{(comment character)} +@cindex Catcode for comments in @TeX{} +In cases of nested command invocations, complicated macro definitions, +etc., @code{@@c} and @code{@@comment} may provoke an error when +processing with @TeX{}. Therefore, you can also use the @kbd{DEL} +character (ASCII 127 decimal, 0x7f hex, 0177 octal) as a true @TeX{} +comment character (catcode 14, in @TeX{} internals). Everything on +the line after the @kbd{DEL} will be ignored. + +@cindex Ignored text +@cindex Unprocessed text +@findex ignore +You can also have long stretches of text ignored by the Texinfo +processors with the @code{@@ignore} and @code{@@end ignore} commands. +Write each of these commands on a line of its own, starting each +command at the beginning of the line. Text between these two commands +does not appear in the processed output. You can use @code{@@ignore} +and @code{@@end ignore} for writing comments. (For some caveats +regarding nesting of such commands, @pxref{Conditional Nesting}.) + + +@node Minimum +@section What a Texinfo File Must Have +@cindex Minimal Texinfo file (requirements) +@cindex Must have in Texinfo file +@cindex Required in Texinfo file +@cindex Texinfo file minimum + +By convention, the name of a Texinfo file ends with one of the +extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or +@file{.tex}.@footnote{The longer extensions are preferred, since they +describe more clearly to a human reader the nature of the file. The +shorter extensions are for operating systems that cannot handle long +file names.} + +In order to be made into a printed manual and other output +formats, a Texinfo file must begin with lines like this: + +@example +@group +\input texinfo +@@settitle @var{name-of-manual} +@end group +@end example + +@noindent +The contents of the file follow this beginning, and then you +must end the Texinfo source with a line like this: + +@example +@@bye +@end example + +@findex \input @r{(raw @TeX{} startup)} +@noindent +Here's an explanation: + +@itemize @bullet +@item +The @samp{\input texinfo} line tells @TeX{} to use the +@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo +@@-commands into @TeX{} typesetting commands. (Note the use of the +backslash, @samp{\}; this is correct for @TeX{}.) + +@item +The @code{@@settitle} line specifies a title for the page headers (or +footers) of the printed manual, and the default title and document +description for the @samp{<head>} in HTML@. Strictly speaking, +@code{@@settitle} is optional---if you don't mind your document being +titled `Untitled'. + +@item +The @code{@@bye} line at the end of the file on a line of its own tells +the formatters that the file is ended and to stop formatting. If you +leave this out, you'll be dumped at @TeX{}'s prompt at the end of the +run. +@end itemize + +Furthermore, you will usually provide a Texinfo file with a title page, +indices, and the like, all of which are explained in this manual. But +the minimum, which can be useful for short documents, is just the two +lines at the beginning and the one line at the end. + + + +@node Short Sample +@section A Short Sample Texinfo File +@cindex Sample Texinfo file, with comments + +Here is a short but complete Texinfo file, so you can see how Texinfo +source appears in practice. The first three parts of the file are +mostly boilerplate: when writing a manual, you simply change +the names as appropriate. + +The complete file, without interspersed comments, is shown in +@ref{Short Sample Texinfo File}. + +@xref{Beginning and Ending a File}, for more documentation on the +commands listed here. + + +@subheading Header + +@noindent +The header tells @TeX{} which definitions file to +use, names the manual, and carries out other such housekeeping tasks. + +@example +@group +\input texinfo +@@settitle Sample Manual 1.0 +@end group +@end example + + +@subheading Summary Description and Copyright + +This segment describes the document and contains the copyright notice +and copying permissions. This is done with the @code{@@copying} command. + +@noindent +A real manual includes more text here, according to the license under +which it is distributed. @xref{GNU Sample Texts}. + +@example +@group +@@copying +This is a short example of a complete Texinfo file, version 1.0. + +Copyright @@copyright@{@} 2016 Free Software Foundation, Inc. +@@end copying +@end group +@end example + +@subheading Titlepage, Copyright, Contents + +The title and copyright segment contains the title and copyright +pages for the printed manual. The segment must be enclosed between +@code{@@titlepage} and @code{@@end titlepage} commands. The title and +copyright page does not appear in the online output. + +@noindent +We use the @code{@@insertcopying} command to +include the permission text from the previous section, instead of +writing it out again; it is output on the back of the title page. The +@code{@@contents} command generates a table of contents. + +@example +@group +@@titlepage +@@title Sample Title +@end group + +@group +@@c The following two commands start the copyright page. +@@page +@@vskip 0pt plus 1filll +@@insertcopying +@@end titlepage +@end group + +@@c Output the table of contents at the beginning. +@@contents +@end example + +@subheading `Top' Node and Master Menu + +The `Top' node starts off the online output; it does not appear in the +printed manual. We repeat the short description from the beginning of +the @samp{@@copying} text, but there's no need to repeat the copyright +information, so we don't use @samp{@@insertcopying} here. + +The @samp{@@top} command itself helps @command{makeinfo} determine +the relationships between nodes. The `Top' node contains at least a +top-level @dfn{menu} listing the chapters, and possibly a @dfn{Master +Menu} listing all the nodes in the entire document. + + +@example +@@ifnottex +@@node Top +@@top Short Sample + +This is a short sample Texinfo file. +@@end ifnottex + +@group +@@menu +* First Chapter:: The first chapter is the + only chapter in this sample. +* Index:: Complete index. +@@end menu +@end group +@end example + + +@subheading The Body of the Document + +@noindent +The body segment contains all the text of the document, but not the +indices or table of contents. This example illustrates a node and a +chapter containing an enumerated list. + +@example +@group +@@node First Chapter +@@chapter First Chapter + +@@cindex chapter, first +@end group + +@group +This is the first chapter. +@@cindex index entry, another +@end group + +@group +Here is a numbered list. + +@@enumerate +@@item +This is the first item. + +@@item +This is the second item. +@@end enumerate +@end group +@end example + + +@subheading The End of the Document + +This may contain commands for printing indices, and +closes with the @code{@@bye} command, which marks the end of the document. + +@example +@group +@@node Index +@@unnumbered Index +@end group + +@group +@@printindex cp + +@@bye +@end group +@end example + + +@subheading Some Results + +Here is what the contents of the first chapter of the sample look like: + +@sp 1 +@need 700 +@quotation +This is the first chapter. + +Here is a numbered list. + +@enumerate +@item +This is the first item. + +@item +This is the second item. +@end enumerate +@end quotation + + +@node Beginning and Ending a File +@anchor{Beginning a File} @c old name +@chapter Beginning and Ending a Texinfo File +@cindex Beginning a Texinfo file +@cindex Texinfo file beginning +@cindex File beginning + +This chapter expands on the minimal complete Texinfo source file +previously given (@pxref{Short Sample}). + +Certain pieces of information must be provided at the beginning of a +Texinfo file, such the title of the document and the Top node. A table +of contents is also generally produced here. + +@cindex Frontmatter, text in +Straight text outside of any command before the Top node should be +avoided. Such text is treated differently in the different output +formats: at the time of writing, it is visible in @TeX{} and HTML, by +default not shown in Info readers, and so on. + +@menu +* Sample Beginning:: A sample beginning for a Texinfo file. +* Texinfo File Header:: The first lines. +* Document Permissions:: Ensuring your manual is free. +* Titlepage & Copyright Page:: Creating the title and copyright pages. +* Contents:: How to create a table of contents. +* The Top Node:: Creating the `Top' node and master menu. +* Global Document Commands:: Affecting formatting throughout. +* Ending a File:: What is at the end of a Texinfo file? +@end menu + + +@node Sample Beginning +@section Sample Texinfo File Beginning + +@cindex Example beginning of Texinfo file + +The following sample shows what is needed. The elements given here are +explained in more detail in the following sections. Other commands are +often included at the beginning of Texinfo files, but the ones here are +the most critical. + +@xref{GNU Sample Texts}, for the full texts to be used in GNU manuals. + +@example +\input texinfo +@@settitle @var{name-of-manual} @var{version} + +@@copying +This manual is for @var{program}, version @var{version}. + +Copyright @@copyright@{@} @var{years} @var{copyright-owner}. + +@group +@@quotation +Permission is granted to @dots{} +@@end quotation +@@end copying +@end group + +@group +@@titlepage +@@title @var{name-of-manual-when-printed} +@@subtitle @var{subtitle-if-any} +@@subtitle @var{second-subtitle} +@@author @var{author} +@end group + +@group +@@c The following two commands +@@c start the copyright page. +@@page +@@vskip 0pt plus 1filll +@@insertcopying +@end group + +Published by @dots{} +@@end titlepage + +@@c So the toc is printed at the start. +@@contents + +@@ifnottex +@@node Top +@@top @var{title} + +This manual is for @var{program}, version @var{version}. +@@end ifnottex + +@group +@@menu +* First Chapter:: Getting started @dots{} +* Second Chapter:: @dots{} + @dots{} +* Copying:: Your rights and freedoms. +@@end menu +@end group + +@group +@@node First Chapter +@@chapter First Chapter + +@@cindex first chapter +@@cindex chapter, first +@dots{} +@end group +@end example + + +@node Texinfo File Header +@section Texinfo File Header +@cindex Header for Texinfo files +@cindex Texinfo file header + +Texinfo files start with at least two lines. These are the +@code{\input texinfo} line and the @code{@@settitle} line. + +Also, if you want to format just part of the Texinfo file in Emacs, +you must write the @code{@@settitle} line between start-of-header and +end-of-header lines. These start- and end-of-header lines are optional, +but they do no harm, so you might as well always include them. + +Any command that affects document formatting as a whole makes sense to +include in the header. @code{@@synindex} (@pxref{@code{@@synindex}}), +for instance, is another command often included in the header. + +Thus, the beginning of a Texinfo file looks approximately +like this: + +@example +@group +\input texinfo +@@settitle Sample Manual 1.0 +@end group +@end example + +(@xref{GNU Sample Texts} for complete sample texts.) + +@menu +* First Line:: The first line of a Texinfo file. +* Start of Header:: Formatting a region requires this. +* @code{@@setfilename}:: Tell Info the name of the Info file. +* @code{@@settitle}:: Create a title for the printed work. +* End of Header:: Formatting a region requires this. +@end menu + + +@node First Line +@subsection The First Line of a Texinfo File +@cindex First line of a Texinfo file +@cindex Beginning line of a Texinfo file +@cindex Header of a Texinfo file + +Every Texinfo file that is to be the top-level input to @TeX{} must begin +with a line that looks like this: + +@example +\input texinfo +@end example + +When the file is processed by @TeX{}, the @samp{\input texinfo} command +tells @TeX{} to load the macros needed for processing a Texinfo file. +These are in a file called @file{texinfo.tex}, which should have been +installed on your system along with either the @TeX{} or Texinfo +software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of +a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex} +file causes the switch from @samp{\} to @samp{@@}; before the switch +occurs, @TeX{} requires @samp{\}, which is why it appears at the +beginning of the file. + +You may optionally follow this line with a comment to tell GNU Emacs +to use Texinfo mode when the file is edited: + +@example +\input texinfo @@c -*-texinfo-*- +@end example + +@noindent This may be useful when Emacs doesn't detect the file type +from the file extension automatically. + +@node Start of Header +@subsection Start of Header +@cindex Start of header line + +A start-of-header line is a Texinfo comment that looks like this: + +@example +@@c %**start of header +@end example + +Write the start-of-header line on the second line of a Texinfo file. +Follow the start-of-header line with an @code{@@settitle} line and, +optionally, with other commands that globally affect the document +formatting, such as @code{@@synindex} or @code{@@footnotestyle}; and +then by an end-of-header line (@pxref{End of Header}). + +The start- and end-of-header lines allow you to format only part of a +Texinfo file for Info or printing. @xref{@code{texinfo-format} commands}. + +The odd string of characters, @samp{%**}, is to ensure that no other +comment is accidentally taken for a start-of-header line. You can +change it if you wish by setting the @code{tex-start-of-header} and/or +@code{tex-end-of-header} Emacs variables. @xref{Texinfo Mode Printing}. + + +@node @code{@@setfilename} +@subsection @code{@@setfilename}: Set the Output File Name + +@anchor{setfilename}@c old name +@findex setfilename +@cindex Texinfo requires @code{@@setfilename} +@cindex Output file name, required + +The @code{@@setfilename} line specifies the name of the output file to +be generated. +When present, it should be the first Texinfo command (that is, after +@samp{\input texinfo}). +Write the @code{@@setfilename} command at the beginning of a line and +follow it on the same line by the Info file name. + +@example +@@setfilename @var{info-file-name} +@end example + +The name must be different from the name of the +Texinfo file. There are two conventions for choosing the name: you +can either remove the extension (such as @samp{.texi}) entirely from +the input file name, or (recommended) replace it with the @samp{.info} +extension. + +@cindex Ignored before @code{@@setfilename} +@cindex @samp{\input} source line ignored +When a @code{@@setfilename} line is present, the Texinfo processors +ignore everything written before the @code{@@setfilename} line. This +is why the very first line of the file (the @code{\input} line) does +not show up in the output. + +If there is no @code{@@setfilename} line, @code{makeinfo} uses the +input file name to determine the output name: first, any of the +extensions @code{.texi}, @code{.tex}, @code{.txi} or @code{.texinfo} +is removed from the input file name; then, the output format specific +extension is added---@code{.html} when generating HTML, @code{.info} +when generating Info, etc. The @code{\input} line is still ignored in +this processing, as well as leading blank lines. + +When producing another output format, @code{makeinfo} will replace any +final extension with the output format-specific extension (@samp{html} +when generating HTML, for example), or add a dot followed by the +extension (@samp{.html} for HTML) if the given name has no extension. + +@code{@@setfilename} used to be required by the Texinfo processors, and +some other programs may still expect it to be present; for example, +Automake (@pxref{Texinfo,,,automake, GNU Automake}). + +@cindex Length of file names +@cindex File name collision +@cindex Info file name, choosing +Although an explicit @samp{.info} extension is preferable, some +operating systems cannot handle long file names. You can run into a +problem even when the file name you specify is itself short enough. +This occurs because the Info formatters split a long Info file into +short indirect subfiles, and name them by appending @samp{-1}, +@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original +file name. (@xref{Tag and Split Files}.) The subfile name +@file{texinfo.info-10}, for example, is too long for old systems with +a 14-character limit on filenames; so the Info file name for this +document is @file{texinfo} rather than @file{texinfo.info}. When +@code{makeinfo} is running on operating systems such as MS-DOS which +impose severe limits on file names, it may remove some characters from +the original file name to leave enough space for the subfile suffix, +thus producing files named @file{texin-10}, @file{gcc.i12}, etc. + +See also the @option{--output} option in @ref{Invoking @command{texi2any}}. + + +@node @code{@@settitle} +@subsection @code{@@settitle}: Set the Document Title + +@anchor{settitle}@c old name +@findex settitle +@cindex Document title, specifying + +A Texinfo file should contain a line that looks like this: + +@example +@@settitle @var{title} +@end example + +Write the @code{@@settitle} command at the beginning of a line and +follow it on the same line by the title. Do not write anything else +on the line. The @code{@@settitle} command should precede everything +that generates actual output. The best place for it is right after +the @code{@@setfilename} command (described in the previous section). + +This command tells @TeX{} the title to use in a header or footer +for double-sided output, in case such headings are output. For +more on headings for @TeX{}, see @ref{Heading Generation}. + +@cindex @code{<title>} HTML tag +In the HTML file produced by @command{makeinfo}, @var{title} serves as +the document @samp{<title>}. It also becomes the default document +description in the @samp{<head>} part +(@pxref{@code{@@documentdescription}}). + +When the title page is used in the output, the title in the +@code{@@settitle} command does not affect the title as it appears on +the title page. Thus, the two do not need not to match exactly. A +practice we recommend is to include the version or edition number of +the manual in the @code{@@settitle} title; on the title page, the +version number generally appears as a @code{@@subtitle} so it would +be omitted from the @code{@@title}. @xref{@code{@@titlepage}}. + + +@node End of Header +@subsection End of Header +@cindex End of header line + +Follow the header lines with an @w{end-of-header} line, which is a +Texinfo comment that looks like this: + +@example +@@c %**end of header +@end example + +@xref{Start of Header}. + + +@node Document Permissions +@section Document Permissions +@cindex Document Permissions +@cindex Copying Permissions + +The copyright notice and copying permissions for a document need to +appear in several places in the various Texinfo output formats. +Therefore, Texinfo provides a command (@code{@@copying}) to declare +this text once, and another command (@code{@@insertcopying}) to +insert the text at appropriate points. + +@anchor{Software Copying Permissions}@c old node name +This section is about the license of the Texinfo document. If the +document is a software manual, the software is typically under a +different license---for GNU and many other free software packages, +software is usually released under the GNU GPL, and manuals are +released under the GNU FDL@. It is helpful to state the license of +the software of the manual, but giving the complete text of the +software license is not necessarily required. + +@menu +* @code{@@copying}:: Declare the document's copying permissions. +* @code{@@insertcopying}:: Where to insert the permissions. +@end menu + + +@node @code{@@copying} +@subsection @code{@@copying}: Declare Copying Permissions + +@anchor{copying}@c old name +@findex copying + +The @code{@@copying} command should be given very early in the document; +the recommended location is right after the header material +(@pxref{Texinfo File Header}). It conventionally consists of a sentence +or two about what the program is, identification of the documentation +itself, the legal copyright line, and the copying permissions. Here is +a skeletal example: + +@example +@@copying +This manual is for @var{program} (version @var{version}, updated +@var{date}), which @dots{} + +Copyright @@copyright@{@} @var{years} @var{copyright-owner}. + +@@quotation +Permission is granted to @dots{} +@@end quotation +@@end copying +@end example + +The @code{@@quotation} has no legal significance; it's there to improve +readability in some contexts. + +The text of @code{@@copying} is output as a comment at the beginning +of Info, HTML, XML, and Docbook output files. It is @emph{not} output +implicitly in plain text or @TeX{}; it's up to you to use +@code{@@insertcopying} to emit the copying information. See the next +section for details. + +@findex copyright +The @code{@@copyright@{@}} command generates a @samp{c} inside a +circle when the output format supports this glyph (print and HTML +always do, for instance). When the glyph is not supported in the +output, it generates the three-character sequence @samp{(C)}. + +The copyright notice itself has the following legally-prescribed +form: + +@example +Copyright @copyright{} @var{years} @var{copyright-owner}. +@end example + +@cindex Copyright word, always in English +The word `Copyright' must always be written in English, even if the +document is otherwise written in another language. This is due to +international law. + +@cindex Years, in copyright line +The list of years should include all years in which a version was +completed (even if it was released in a subsequent year). It is +simplest for each year to be written out individually and in full, +separated by commas. + +@cindex Copyright holder for FSF works +@cindex Holder of copyright for FSF works +@cindex Owner of copyright for FSF works +The copyright owner (or owners) is whoever holds legal copyright on the +work. In the case of works assigned to the FSF, the owner is `Free +Software Foundation, Inc.'. + +The copyright `line' may actually be split across multiple lines, both +in the source document and in the output. This often happens for +documents with a long history, having many different years of +publication. If you do use several lines, do not indent any of them +(or anything else in the @code{@@copying} block) in the source file. + +@xref{Copyright Notices,,, maintain, GNU Maintainer Information}, for +additional information. @xref{GNU Sample Texts}, for the full text to +be used in GNU manuals. @xref{GNU Free Documentation License}, for +the license itself under which GNU and other free manuals are +distributed. + + +@node @code{@@insertcopying} +@subsection @code{@@insertcopying}: Include Permissions Text + +@anchor{insertcopying}@c old name +@findex insertcopying +@cindex Copying text, including +@cindex Permissions text, including +@cindex Including permissions text + +The @code{@@insertcopying} command is simply written on a line by +itself, like this: + +@example +@@insertcopying +@end example + +This inserts the text previously defined by @code{@@copying}. To meet +legal requirements, it must be used on the copyright page in the printed +manual (@pxref{Copyright}). + +The @code{@@copying} command itself causes the permissions text to +appear in an Info file @emph{before} the first node. The text is also +copied into the beginning of each split Info output file, as is legally +necessary. This location implies a human reading the manual using Info +does @emph{not} see this text (except when using the advanced Info +command @kbd{g *}), but this does not matter for legal purposes, +because the text is present. + +Similarly, the @code{@@copying} text is automatically included at the +beginning of each HTML output file, as an HTML comment. Again, this +text is not visible (unless the reader views the HTML source). + +The permissions text defined by @code{@@copying} also appears +automatically at the beginning of the XML and Docbook output files. + + +@node Titlepage & Copyright Page +@section Title and Copyright Pages + +In hard copy output, the manual's name and author are usually printed on +a title page. Copyright information is usually printed on the back of +the title page. + +The title and copyright pages appear in printed manuals, but not in +most other output formats. Because of this, it is possible to use +several slightly obscure typesetting commands that are not to be used +in the main text. In addition, this part of the beginning of a +Texinfo file contains the text of the copying permissions that appears +in the printed manual. + +@menu +* @code{@@titlepage}:: Create a title for the printed document. +* @code{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center}, + and @code{@@sp} commands. +* @code{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle}, + and @code{@@author} commands. +* Copyright:: How to write the copyright notice and + include copying permissions. +* Heading Generation:: Turn on page headings after the title and + copyright pages. +@end menu + + +@node @code{@@titlepage} +@subsection @code{@@titlepage} + +@anchor{titlepage}@c old name +@cindex Title page +@findex titlepage + +Start the material for the title page and following copyright page +with @code{@@titlepage} on a line by itself and end it with +@code{@@end titlepage} on a line by itself. + +The @code{@@end titlepage} command starts a new page and turns on page +numbering (@pxref{Heading Generation}). All the +material that you want to appear on unnumbered pages should be put +between the @code{@@titlepage} and @code{@@end titlepage} commands. +You can force the table of contents to appear there with the +@code{@@setcontentsaftertitlepage} command (@pxref{Contents}). + +@findex page@r{, within @code{@@titlepage}} +By using the @code{@@page} command you can force a page break within the +region delineated by the @code{@@titlepage} and @code{@@end titlepage} +commands and thereby create more than one unnumbered page. This is how +the copyright page is produced. (The @code{@@titlepage} command might +perhaps have been better named the @code{@@titleandadditionalpages} +command, but that would have been rather long!) + +When you write a manual about a computer program, you should write the +version of the program to which the manual applies on the title page. +If the manual changes more frequently than the program or is independent +of it, you should also include an edition number@footnote{We have found +that it is helpful to refer to versions of independent manuals as +`editions' and versions of programs as `versions'; otherwise, we find we +are liable to confuse each other in conversation by referring to both +the documentation and the software with the same words.} for the manual. +This helps readers keep track of which manual is for which version of +the program. (The `Top' node should also contain this information; see +@ref{The Top Node}.) + +Texinfo provides two main methods for creating a title page. One method +uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands +to generate a title page in which the words on the page are +centered. + +The second method uses the @code{@@title}, @code{@@subtitle}, and +@code{@@author} commands to create a title page with black rules under +the title and author lines and the subtitle text set flush to the +right hand side of the page. With this method, you do not specify any +of the actual formatting of the title page. You specify the text +you want, and Texinfo does the formatting. + +You may use either method, or you may combine them; see the examples in +the sections below. + +@findex shorttitlepage +@cindex Bastard title page +@cindex Title page, bastard +For sufficiently simple documents, and for the bastard title page in +traditional book frontmatter, Texinfo also provides a command +@code{@@shorttitlepage} which takes the rest of the line as the title. +The argument is typeset on a page by itself and followed by a blank +page. + + +@node @code{@@titlefont @@center @@sp} +@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} + +@anchor{titlefont center sp}@c old name +@findex titlefont +@findex center +@findex sp @r{(titlepage line spacing)} + +You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} +commands to create a title page for a printed document. (This is the +first of the two methods for creating a title page in Texinfo.) + +Use the @code{@@titlefont} command to select a large font suitable for +the title itself. You can use @code{@@titlefont} more than once if you +have an especially long title. + +For HTML output, each @code{@@titlefont} command produces an +@code{<h1>} heading, but the HTML document @code{<title>} is not +affected. For that, you must put a @code{@@settitle} command before +the @code{@@titlefont} command (@pxref{@code{@@settitle}}). + +@need 700 +For example: + +@example +@@titlefont@{Texinfo@} +@end example + +Use the @code{@@center} command at the beginning of a line to center +the remaining text on that line. Thus, + +@example +@@center @@titlefont@{Texinfo@} +@end example + +@noindent +centers the title, which in this example is ``Texinfo'' printed +in the title font. + +Use the @code{@@sp} command to insert vertical space. For example: + +@example +@@sp 2 +@end example + +@noindent +This inserts two blank lines on the printed page. +(@xref{@code{@@sp}}, for more information about the @code{@@sp} +command.) + +A template for this method looks like this: + +@example +@group +@@titlepage +@@sp 10 +@@center @@titlefont@{@var{name-of-manual-when-printed}@} +@@sp 2 +@@center @var{subtitle-if-any} +@@sp 2 +@@center @var{author} +@dots{} +@@end titlepage +@end group +@end example + +The spacing of the example fits an 8.5 by 11 inch manual. + + +@node @code{@@title @@subtitle @@author} +@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} + +@anchor{title subtitle author}@c old name +@findex title +@findex subtitle +@findex author + +You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} +commands to create a title page in which the vertical and horizontal +spacing is done for you automatically. This contrasts with the method +described in the previous section, in which the @code{@@sp} command is +needed to adjust vertical spacing. + +Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} +commands at the beginning of a line followed by the title, subtitle, +or author. The @code{@@author} command may be used for a quotation in +an @code{@@quotation} block (@pxref{@code{@@quotation}}); +except for that, it is an error to use any of these commands outside +of @code{@@titlepage}. + +The @code{@@title} command produces a line in which the title is set +flush to the left-hand side of the page in a larger than normal font. +The title is underlined with a black rule. The title must be given on +a single line in the source file; it will be broken into multiple +lines of output is needed. + +For long titles, the @code{@@*} command may be used to specify the +line breaks in long titles if the automatic breaks do not suit. Such +explicit line breaks are generally reflected in all output formats; if +you only want to specify them for the printed output, use a +conditional (@pxref{Conditionals}). For example: + +@example +@@title This Long Title@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@} +@end example + +The @code{@@subtitle} command sets subtitles in a normal-sized font +flush to the right-hand side of the page. + +The @code{@@author} command sets the names of the author or authors in +a middle-sized font flush to the left-hand side of the page on a line +near the bottom of the title page. The names are followed by a black +rule that is thinner than the rule that underlines the title. + +There are two ways to use the @code{@@author} command: you can write +the name or names on the remaining part of the line that starts with +an @code{@@author} command: + +@example +@@author by Jane Smith and John Doe +@end example + +@noindent +or you can write the names one above each other by using multiple +@code{@@author} commands: + +@example +@group +@@author Jane Smith +@@author John Doe +@end group +@end example + +@need 950 +A template for this method looks like this: + +@example +@group +@@titlepage +@@title @var{name-of-manual-when-printed} +@@subtitle @var{subtitle-if-any} +@@subtitle @var{second-subtitle} +@@author @var{author} +@@page +@dots{} +@@end titlepage +@end group +@end example + + +@node Copyright +@subsection Copyright Page +@cindex Copyright page +@cindex Printed permissions +@cindex Permissions, printed + +By international treaty, the copyright notice for a book must be either +on the title page or on the back of the title page. When the copyright +notice is on the back of the title page, that page is customarily not +numbered. Therefore, in Texinfo, the information on the copyright page +should be within @code{@@titlepage} and @code{@@end titlepage} +commands. + +@findex vskip @r{@TeX{} vertical skip} +@cindex filll @r{@TeX{} dimension} +Use the @code{@@page} command to cause a page break. To push the +copyright notice and the other text on the copyright page towards the +bottom of the page, use the following incantation after @code{@@page}: + +@example +@@vskip 0pt plus 1filll +@end example + +@noindent +The @code{@@vskip} command inserts whitespace in the @TeX{} output; it +is ignored in all other output formats. The @samp{0pt plus 1filll} +means to put in zero points of mandatory whitespace, and as much +optional whitespace as needed to push the following text to the bottom +of the page. Note the use of three @samp{l}s in the word +@samp{filll}; this is correct. + +To insert the copyright text itself, write @code{@@insertcopying} +next (@pxref{Document Permissions}): + +@example +@@insertcopying +@end example + +Follow the copying text by the publisher, ISBN numbers, cover art +credits, and other such information. + +Here is an example putting all this together: + +@example +@@titlepage +@dots{} +@@page +@@vskip 0pt plus 1filll +@@insertcopying + +Published by @dots{} + +Cover art by @dots{} +@@end titlepage +@end example + +We have one more special case to consider: for plain text output, you +must insert the copyright information explicitly if you want it to +appear. For instance, you could have the following after the copyright +page: + +@example +@@ifplaintext +@@insertcopying +@@end ifplaintext +@end example + +You could include other title-like information for the plain text +output in the same place. + + + +@node Heading Generation +@subsection Heading Generation + +@anchor{end titlepage}@c old name +@cindex Headings, page, begin to appear +@cindex Titlepage end starts headings +@cindex End titlepage starts headings +@cindex Generating page headings + +Like all @code{@@end} commands (@pxref{Quotations and Examples}), the +@code{@@end titlepage} command must be written at the beginning of a +line by itself, with only one space between the @code{@@end} and the +@code{titlepage}. It not only marks the end of the title and +copyright pages, but also causes @TeX{} to start generating page +headings and page numbers. + +Texinfo has two standard page heading formats, one for documents +printed on one side of each sheet of paper (single-sided printing), +and the other for documents printed on both sides of each sheet +(double-sided printing). + +In full generality, you can control the headings in different ways: + +@itemize @bullet +@item +The conventional way is to write a @code{@@setchapternewpage} command +before the title page commands, if required, and then have the +@code{@@end titlepage} command start generating page headings in the +manner desired. + +Most documents are formatted with the standard single-sided or +double-sided headings, (sometimes) using @code{@@setchapternewpage +odd} for double-sided printing and (almost always) no +@code{@@setchapternewpage} command for single-sided printing +(@pxref{@code{@@setchapternewpage}}). + +@item +Alternatively, you can use the @code{@@headings} command to prevent +page headings from being generated or to start them for either single +or double-sided printing. Write a @code{@@headings} command +immediately after the @code{@@end titlepage} command. To turn off +headings, write @code{@@headings off}. @xref{@code{@@headings}}. + +@item +Or, you may specify your own page heading and footing format. +@xref{Headings}. +@end itemize + + +@node Contents +@section Generating a Table of Contents +@cindex Table of contents +@cindex Contents, table of +@cindex Short table of contents +@findex contents +@findex summarycontents +@findex shortcontents + +The @code{@@chapter}, @code{@@section}, and other structuring commands +(@pxref{Chapter Structuring}) supply the information to make up a +table of contents, but they do not cause an actual table to appear in +the manual. To do this, you must use the @code{@@contents} and/or +@code{@@summarycontents} command(s). + +@table @code +@item @@contents +Generates a table of contents in a printed manual, including all +chapters, sections, subsections, etc., as well as appendices and +unnumbered chapters. Headings generated by @code{@@majorheading}, +@code{@@chapheading}, and the other @code{@@@dots{}heading} commands +do not appear in the table of contents (@pxref{Structuring Command +Types}). + +@item @@shortcontents +@itemx @@summarycontents +(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.) + +Generates a short or summary table of contents that lists only the +chapters, appendices, and unnumbered chapters. Sections, subsections +and subsubsections are omitted. Only a long manual needs a short +table of contents in addition to the full table of contents. +@end table + +Both contents commands should be written on a line by themselves, and +placed near the beginning of the file, after the @code{@@end +titlepage} (@pxref{@code{@@titlepage}}), before any sectioning +command. The contents commands automatically generate a chapter-like +heading at the top of the first table of contents page, so don't +include any sectioning command such as @code{@@unnumbered} before +them. + +Since an Info file uses menus instead of tables of contents, the Info +formatting commands ignore the contents commands. But the contents +are included in plain text output (generated by @code{makeinfo +--plaintext}) and in other output formats, such as HTML. + +When @code{makeinfo} writes a short table of contents while producing +HTML output, the links in the short table of contents point to +corresponding entries in the full table of contents rather than the text +of the document. The links in the full table of contents point to the +main text of the document. + + +@node The Top Node +@section The `Top' Node and Master Menu +@cindex Top node +@cindex Node, `Top' + +The `Top' node is the node in which a reader enters an Info manual. +As such, it should begin with a brief description of the manual +(including the version number), and end with a master menu for the +whole manual. Of course you should include any other general +information you feel a reader would find helpful. + +@findex top +It is conventional and desirable to write a @code{@@top} sectioning +command line containing the title of the document immediately after +the @code{@@node Top} line (@pxref{@code{@@top} Command}). + +The contents of the `Top' node should appear only in the online output; +none of it should appear in printed output, so enclose it between +@code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not +print either an @code{@@node} line or a menu; they appear only in Info; +strictly speaking, you are not required to enclose these parts between +@code{@@ifnottex} and @code{@@end ifnottex}, but it is simplest to do +so. @xref{Conditionals, , Conditionally Visible Text}.) + +@menu +* Top Node Example:: +* Master Menu Parts:: +@end menu + + +@node Top Node Example +@subsection Top Node Example + +@cindex Top node example + +Here is an example of a Top node. + +@example +@group +@@ifnottex +@@node Top +@@top Sample Title + +This is the text of the top node. +@@end ifnottex +@end group + +Additional general information. + +@group +@@menu +* First Chapter:: +* Second Chapter:: +@dots{} +* Index:: +@end group +@@end menu +@end example + + +@node Master Menu Parts +@subsection Parts of a Master Menu +@cindex Master menu +@cindex Menu, master +@cindex Parts of a master menu + +A @dfn{master menu} is the main menu. It is customary to include a +detailed menu listing all the nodes in the document in this menu. + +Like any other menu, a master menu is enclosed in @code{@@menu} and +@code{@@end menu} and does not appear in the printed output. + +Generally, a master menu is divided into parts. + +@itemize @bullet +@item +The first part contains the major nodes in the Texinfo file: the nodes +for the chapters, chapter-like sections, and the appendices. + +@item +The second part contains nodes for the indices. + +@item +@findex detailmenu +@cindex Detailed menu +The third and subsequent parts contain a listing of the other, +lower-level nodes, often ordered by chapter. This way, rather than go +through an intermediary menu, an inquirer can go directly to a +particular node when searching for specific information. These menu +items are not required; add them if you think they are a convenience. +If you do use them, put @code{@@detailmenu} before the first one, and +@code{@@end detailmenu} after the last; otherwise, @code{makeinfo} +will get confused. +@end itemize + +Each section in the menu can be introduced by a descriptive line. So +long as the line does not begin with an asterisk, it will not be +treated as a menu entry. (@xref{Writing a Menu}, for more +information.) + +For example, the master menu for this manual looks like the following +(but has many more entries): + +@example +@group +@@menu +* Copying Conditions:: Your rights. +* Overview:: Texinfo in brief. +@dots{} +@end group +@group +* Command and Variable Index:: +* General Index:: +@end group + +@group +@@detailmenu +--- The Detailed Node Listing --- + +Overview of Texinfo + +* Reporting Bugs:: @dots{} +@dots{} +@end group + +@group +Beginning a Texinfo File + +* Sample Beginning:: @dots{} +@dots{} +@@end detailmenu +@@end menu +@end group +@end example + + +@node Global Document Commands +@section Global Document Commands +@cindex Global Document Commands + +Besides the basic commands mentioned in the previous sections, here are +additional commands which affect the document as a whole. They are +generally all given before the Top node, if they are given at all. + +@menu +* @code{@@documentdescription}:: Document summary for the HTML output. +* @code{@@setchapternewpage}:: Start chapters on right-hand pages. +* @code{@@headings}:: An option for turning headings on and off + and double or single sided printing. +* @code{@@paragraphindent}:: Specify paragraph indentation. +* @code{@@firstparagraphindent}:: Suppressing first paragraph indentation. +* @code{@@exampleindent}:: Specify environment indentation. +@end menu + + +@node @code{@@documentdescription} +@subsection @code{@@documentdescription}: Summary Text +@anchor{documentdescription}@c old name + +@cindex Document description +@cindex Description of document +@cindex Summary of document +@cindex Abstract of document +@cindex @code{<meta>} HTML tag, and document description +@findex documentdescription + +When producing HTML output for a document, @command{makeinfo} writes a +@samp{<meta>} element in the @samp{<head>} to give some idea of the +content of the document. By default, this @dfn{description} is the +title of the document, taken from the @code{@@settitle} command +(@pxref{@code{@@settitle}}). To change this, use the +@code{@@documentdescription} environment, as in: + +@example +@@documentdescription +descriptive text. +@@end documentdescription +@end example + +@noindent +This will produce the following output in the @samp{<head>} of the HTML: + +@example +<meta name=description content="descriptive text."> +@end example + +@code{@@documentdescription} must be specified before the first node of +the document. + + +@node @code{@@setchapternewpage} +@subsection @code{@@setchapternewpage}: Blank Pages Before Chapters + +@anchor{setchapternewpage}@c old name +@findex setchapternewpage +@cindex Starting chapters +@cindex Pages, starting odd + +In an officially bound book, text is usually printed on both sides of +the paper, chapters start on right-hand pages, and right-hand pages have +odd numbers. But in short reports, text often is printed only on one +side of the paper. Also in short reports, chapters sometimes do not +start on new pages, but are printed on the same page as the end of the +preceding chapter, after a small amount of vertical whitespace. + +You can use the @code{@@setchapternewpage} command with various +arguments to specify how @TeX{} should start chapters and whether it +should format headers for printing on one or both sides of the paper +(single-sided or double-sided printing). + +Write the @code{@@setchapternewpage} command at the beginning of a +line followed by its argument. + +For example, you would write the following to cause each chapter to +start on a fresh odd-numbered page: + +@example +@@setchapternewpage odd +@end example + +You can specify one of three alternatives with the +@code{@@setchapternewpage} command: + +@table @asis + +@item @code{@@setchapternewpage off} +Cause @TeX{} to typeset a new chapter on the same page as the last +chapter, after skipping some vertical whitespace. Also, cause @TeX{} to +format page headers for single-sided printing. + +@item @code{@@setchapternewpage on} +Cause @TeX{} to start new chapters on new pages and to format page +headers for single-sided printing. This is the form most often used for +short reports or personal printing. This is the default. + +@item @code{@@setchapternewpage odd} +Cause @TeX{} to start new chapters on new, odd-numbered pages +(right-handed pages) and to typeset for double-sided printing. This is +the form most often used for books and manuals. +@end table + +Texinfo does not have a @code{@@setchapternewpage even} command, +because there is no printing tradition of starting chapters or books on +an even-numbered page. + +If you don't like the default headers that @code{@@setchapternewpage} +sets, you can explicit control them with the @code{@@headings} command. +@xref{@code{@@headings}}. + +At the beginning of a manual or book, pages are not numbered---for +example, the title and copyright pages of a book are not numbered. By +convention, table of contents and frontmatter pages are numbered with +roman numerals and not in sequence with the rest of the document. + +The @code{@@setchapternewpage} has no effect in output formats that do +not have pages, such as Info and HTML. + +We recommend not including any @code{@@setchapternewpage} command in +your document source at all, since such desired pagination is not +intrinsic to the document. For a particular hard copy run, if you +don't want the default output (no blank pages, same headers on all +pages) use the @option{--texinfo} option to @command{texi2dvi} to +specify the output you want. + + +@node @code{@@headings} +@subsection The @code{@@headings} Command + +@anchor{headings on off}@c old name +@findex headings + +The @code{@@headings} command is rarely used. It specifies what kind of +page headings and footings to print on each page. Usually, this is +controlled by the @code{@@setchapternewpage} command. You need the +@code{@@headings} command only if the @code{@@setchapternewpage} command +does not do what you want, or if you want to turn off predefined page +headings prior to defining your own. Write a @code{@@headings} command +immediately after the @code{@@end titlepage} command. + +You can use @code{@@headings} as follows: + +@table @code +@item @@headings off +Turn off printing of page headings. + +@item @@headings single +Turn on page headings appropriate for single-sided printing. + +@item @@headings double +Turn on page headings appropriate for double-sided printing. + +@item @@headings singleafter +@itemx @@headings doubleafter +Turn on @code{single} or @code{double} headings, respectively, after the +current page is output. + +@item @@headings on +Turn on page headings: @code{single} if @samp{@@setchapternewpage +on}, @code{double} otherwise. +@end table + +For example, suppose you write @code{@@setchapternewpage off} before the +@code{@@titlepage} command to tell @TeX{} to start a new chapter on the +same page as the end of the last chapter. This command also causes +@TeX{} to typeset page headers for single-sided printing. To cause +@TeX{} to typeset for double sided printing, write @code{@@headings +double} after the @code{@@end titlepage} command. + +You can stop @TeX{} from generating any page headings at all by +writing @code{@@headings off} on a line of its own immediately after the +line containing the @code{@@end titlepage} command, like this: + +@example +@@end titlepage +@@headings off +@end example + +@noindent +The @code{@@headings off} command overrides the @code{@@end titlepage} +command, which would otherwise cause @TeX{} to print page headings. + +You can also specify your own style of page heading and footing. +@xref{Headings, , Page Headings}, for more information. + + +@node @code{@@paragraphindent} +@subsection @code{@@paragraphindent}: Controlling Paragraph Indentation + +@anchor{paragraphindent}@c old name +@findex paragraphindent +@cindex Indenting paragraphs, control of +@cindex Paragraph indentation control + +The Texinfo processors may insert whitespace at the beginning of the +first line of each paragraph, thereby indenting that paragraph. You can +use the @code{@@paragraphindent} command to specify this indentation. +Write a @code{@@paragraphindent} command at the beginning of a line +followed by either @samp{asis} or a number: + +@example +@@paragraphindent @var{indent} +@end example + +The indentation is according to the value of @var{indent}: + +@table @asis +@item @code{asis} +Do not change the existing indentation (not implemented in @TeX{}). + +@item @code{none} +@itemx 0 +Omit all indentation. + +@item @var{n} +Indent by @var{n} space characters in Info output, by @var{n} ems in +@TeX{}. + +@end table + +The default value of @var{indent} is 3. @code{@@paragraphindent} is +ignored for HTML output. + +It is best to write the @code{@@paragraphindent} command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. @xref{Start of +Header}. + + +@node @code{@@firstparagraphindent} +@subsection @code{@@firstparagraphindent}: Indenting After Headings + +@anchor{firstparagraphindent}@c old name +@findex firstparagraphindent +@cindex First paragraph, suppressing indentation of +@cindex Suppressing first paragraph indentation +@cindex Preventing first paragraph indentation +@cindex Indenting, suppressing of first paragraph +@cindex Headings, indentation after + +As you can see in the present manual, the first paragraph in any +section is not indented by default. Typographically, indentation is a +paragraph separator, which means that it is unnecessary when a new +section begins. This indentation is controlled with the +@code{@@firstparagraphindent} command: + +@example +@@firstparagraphindent @var{word} +@end example + +The first paragraph after a heading is indented according to the value +of @var{word}: + +@table @asis +@item @code{none} +Prevents the first paragraph from being indented (default). +This option is ignored by @command{makeinfo} if +@code{@@paragraphindent asis} is in effect. + +@item @code{insert} +Include normal paragraph indentation. This respects the paragraph +indentation set by a @code{@@paragraphindent} command +(@pxref{@code{@@paragraphindent}}). +@end table + +@code{@@firstparagraphindent} is ignored for HTML and Docbook output. + +It is best to write the @code{@@firstparagraphindent} command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. @xref{Start of +Header}. + + +@node @code{@@exampleindent} +@subsection @code{@@exampleindent}: Environment Indenting + +@anchor{exampleindent}@c old name +@findex exampleindent +@cindex Indenting environments +@cindex Environment indentation +@cindex Example indentation + +The Texinfo processors indent each line of @code{@@example} and similar +environments. You can use the @code{@@exampleindent} command to specify +this indentation. Write an @code{@@exampleindent} command at the +beginning of a line followed by either @samp{asis} or a number: + +@example +@@exampleindent @var{indent} +@end example + +The indentation is according to the value of @var{indent}: + +@table @asis +@item @code{asis} +Do not change the existing indentation (not implemented in @TeX{}). + +@item 0 +Omit all indentation. + +@item @var{n} +Indent environments by @var{n} space characters in Info output, by +@var{n} ems in @TeX{}. + +@end table + +The default value of @var{indent} is 5 spaces in Info, and 0.4@dmn{in} +in @TeX{}, which is somewhat less. (The reduction is to help @TeX{} +fit more characters onto physical lines.) + +It is best to write the @code{@@exampleindent} command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. @xref{Start of +Header}. + + +@node Ending a File +@section Ending a Texinfo File +@cindex Ending a Texinfo file +@cindex Texinfo file ending +@cindex File ending +@findex bye + +The end of a Texinfo file should include commands to create indices +(@pxref{Printing Indices & Menus}), and the @code{@@bye} command to mark +the last line to be processed. For example: + +@example +@@node Index +@@unnumbered Index + +@@printindex cp + +@@bye +@end example + +@findex bye +@anchor{File End} +An @code{@@bye} command terminates Texinfo processing. None of the +formatters process anything following @code{@@bye}; any such text is +completely ignored. The @code{@@bye} command should be on a line by +itself. + +Thus, if you wish, you may follow the @code{@@bye} line with arbitrary +notes. Also, you may follow the @code{@@bye} line with a local +variables list for Emacs, most typically a @samp{compile-command} +(@pxref{Compile-Command,, Using the Local Variables List}). + + +@node Nodes +@chapter Nodes +@anchor{node}@anchor{@@node} @c old names + +@cindex Node, defined +A @dfn{node} is a region of text that begins at a @code{@@node} +command, and continues until the next @code{@@node} command. +To specify a node, write a @code{@@node} command at the beginning of +a line, and follow it with the name of the node. +Each node contains the discussion of one topic. Info readers +display one node at a time, and provide commands for the user to move +to related nodes. The HTML output can be similarly navigated. + +Nodes are used as the targets of cross-references. Cross-references, +such as the one at the end of this sentence, are made with @code{@@xref} +and related commands; see @ref{Cross References}. Cross-references can +be sprinkled throughout the text, and provide a way to represent links +that do not fit a hierarchical structure. + +Normally, you put a node command immediately before each chapter +structuring command---for example, an @code{@@section} or +@code{@@subsection} line. (@xref{Chapter Structuring}.). +You must do this even if you do not intend to format the file for Info. +This is because @TeX{} uses both @code{@@node} names and +chapter-structuring names in the output for cross-references. The only +time you are likely to use the chapter structuring commands without also +using nodes is if you are writing a document that contains no cross +references and will only be printed, not transformed into Info, HTML, or +other formats. + + +@menu +* Texinfo Document Structure:: Double structure of documents. +* Node Names:: How to choose node names. +* Writing a Node:: How to write an @code{@@node} line. +* Node Line Requirements:: Keep names unique. +* First Node:: How to write a `Top' node. +* @code{@@top} Command:: How to use the @code{@@top} command. +* Node Menu Illustration:: A diagram, and sample nodes and menus. +* @command{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers. +* Menus:: Listing subordinate nodes. +@end menu + + +@node Texinfo Document Structure +@section Texinfo Document Structure +@cindex Texinfo document structure +@cindex Document structure, of Texinfo +@cindex Structure, of Texinfo documents +@cindex Double structure, of Texinfo documents + +@anchor{Two Paths}@c node name + +Nodes can contain @dfn{menus}, which contain the names of @dfn{child +nodes} within the parent node; for example, a node corresponding to a +chapter would have a menu of the sections in that chapter. The menus +allow the user to move to the child nodes in a natural way in the online +output. + +In addition, nodes contain @dfn{node pointers} that name other nodes. +The `Next' and `Previous' pointers form nodes at the same sectioning +level into a chain. As you might imagine, the `Next' pointer links to +the next node, and the `Previous' pointer links to the previous node. +Thus, for example, all the nodes that are at the level of sections +within a chapter are linked together, and the order in this chain +is the same as the order of the children in the menu of the parent +chapter. Each child node records the parent node name as its `Up' +pointer. + +@opindex accesskey@r{, in HTML output of nodes} +The Info and HTML output from @command{makeinfo} for each node includes +links to the `Next', `Previous', and `Up' nodes. The HTML also uses +the @code{accesskey} attribute with the values @samp{n}, @samp{p}, and +@samp{u} respectively. This allows people using web browsers to +follow the navigation using (typically) @kbd{M-@var{letter}}, e.g., +@kbd{M-n} for the `Next' node, from anywhere within the node. +Node pointers and menus provide structure for Info files just as +chapters, sections, subsections, and the like provide structure for +printed books. The two structures are theoretically distinct; in +practice, however, the tree structure of printed books is essentially +always used for the node and menu structure also, as this leads to a +document which is easiest to follow. @xref{Texinfo Document +Structure}. + +Typically, the sectioning structure and the node structure are +completely parallel, with one node for each chapter, section, etc., +and with the nodes following the same hierarchical arrangement as the +sectioning. Thus, if a node is at the logical level of a chapter, its +child nodes are at the level of sections; similarly, the child nodes +of sections are at the level of subsections. + +Although it is technically possible to create Texinfo documents with +only one structure or the other, or for the two structures not to be +parallel, or for either the sectioning or node structure to be +abnormally formed, etc., this is @emph{not at all recommended}. To +the best of our knowledge, all the Texinfo manuals currently in +general use do follow the conventional parallel structure. + + +@node Node Names +@section Choosing Node Names + +@cindex Node names, choosing +The name of a node identifies the node. For all the details of node +names, @pxref{Node Line Requirements}). + +@anchor{Node Line Tips}@c previous node name +Here are some suggestions for node names: + +@itemize @bullet +@item +Try to pick node names that are informative but short. + +In the Info file, the file name, node name, and pointer names are all +inserted on one line, which may run into the right edge of the window. +(This does not cause a problem with Info, but is ugly.) + +@item +Try to pick node names that differ from each other near the beginnings +of their names. This way, it is easy to use automatic name completion in +Info. + +@item +Conventionally, node names are capitalized in the same way as section +and chapter titles. In this manual, initial and significant words are +capitalized; others are not. In other manuals, just initial words and +proper nouns are capitalized. Either way is fine; we recommend just +being consistent. + +@item +In HTML output, any characters in the node name other than plain ASCII +letters, numbers or spaces will be changed in the file name. +(@xref{HTML Xref Node Name Expansion}.) +This can make the URL's for the pages in your manual less user-friendly; +for example in this manual the @samp{@@dots} node is output as +@file{__0040dots.html}. +@end itemize + +Because node names are used in cross-references, it is not desirable +to casually change them once published. Such name changes invalidate +references from other manuals, from mail archives, and so on. + +The pointers from a given node enable you to reach other nodes and +consist simply of the names of those nodes. The pointers are usually +not specified explicitly, as @command{makeinfo} can determine them +(@pxref{@command{makeinfo} Pointer Creation}). + +Normally, a node's `Up' pointer contains the name of the node whose +menu mentions that node. The node's `Next' pointer contains the name +of the node that follows the present node in that menu and its +`Previous' pointer contains the name of the node that precedes it in +that menu. When a node's `Previous' node is the same as its `Up' +node, both pointers name the same node. + +Usually, the first node of a Texinfo file is the `Top' node, and its +`Up' pointer points to the @file{dir} file, which contains the main menu +for all of Info. + + +@node Writing a Node +@section Writing an @code{@@node} Line +@cindex Writing an @code{@@node} line +@cindex @code{@@node} line writing +@cindex Node line writing + +@findex node +The easiest way to write an @code{@@node} line is to write @code{@@node} +at the beginning of a line and then the name of the node, like this: + +@example +@@node @var{node-name} +@end example + +After you have inserted an @code{@@node} line, you should immediately +write an @@-command for the chapter or section and insert its name. +Next (and this is important!), put in several index entries. Usually, +you will find at least two and often as many as four or five ways of +referring to the node in the index. Use them all. This will make it +much easier for people to find the node. + +If you wish, you can ignore @code{@@node} lines altogether in your +first draft and then use the @code{texinfo-insert-node-lines} command +to create @code{@@node} lines for you. However, we do not recommend +this practice. It is better to name the node itself at the same time +that you write a segment so you can easily make cross-references. +Useful cross-references are an especially important feature of a good +Texinfo manual. + +Even when you explicitly specify all pointers, you cannot write the +nodes in the Texinfo source file in an arbitrary order! Because +formatters must process the file sequentially, irrespective of node +pointers, you must write the nodes in the order you wish them to +appear in the output. For Info format one can imagine that the order +may not matter, but it matters for the other formats. + +You may optionally follow the node name argument to @code{@@node} +with up to three optional arguments on the rest of the same line, +separating the arguments with commas. These are the names of the +`Next', `Previous', and `Up' pointers, in that order. We recommend +omitting them if your Texinfo document is hierarchically organized, +as virtually all are (@pxref{@command{makeinfo} Pointer Creation}). + +Any spaces before or after each name on the @code{@@node} line are +ignored. + +The template for a fully-written-out node line with `Next', `Previous', +and `Up' pointers looks like this: + +@example +@@node @var{node-name}, @var{next}, @var{previous}, @var{up} +@end example + +The @var{node-name} argument must be present, but the others are +optional. If you wish to specify some but not others, just insert +commas as needed, as in: @samp{@@node mynode,,,uppernode}. However, +we recommend leaving off all the pointers and letting @code{makeinfo} +determine them. + +If you are using GNU Emacs, you can use the update node commands +provided by Texinfo mode to insert the names of the pointers; or +(recommended), you can leave the pointers out of the Texinfo file and +let @code{makeinfo} insert node pointers into the Info file it +creates. (@xref{Texinfo Mode}, and @ref{@command{makeinfo} Pointer +Creation}.) + +Alternatively, you can insert the `Next', `Previous', and `Up' +pointers yourself. If you do this, you may find it helpful to use the +Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts +@samp{@@node} and a comment line listing the names of the pointers in +their proper order. The comment line helps you keep track of which +arguments are for which pointers. This comment line is especially useful +if you are not familiar with Texinfo. + + +@node Node Line Requirements +@section @code{@@node} Line Requirements + +@cindex Node line requirements +@cindex Restrictions on node names + +Names used with @code{@@node} have several requirements: + +@itemize @bullet +@item +@cindex Unique node names requirement +@cindex Node names must be unique +All the node names in a single Texinfo file must be unique. + +This means, for example, that if you end every chapter with a summary, +you must name each summary node differently. You cannot just call +them all ``Summary''. You may, however, duplicate the titles of +chapters, sections, and the like. Thus you can end each chapter with +a section called ``Summary'', so long as the node names for those +sections are all different. + +@item +@cindex Commands in node names +@cindex @@-commands in node names +Node names can contain @@-commands. The output is generally the +natural result of the command; for example, using @code{@@TeX@{@}} in a +node name results in the @TeX{} logo being output, as it would be in +normal text. Cross-references should use @code{@@TeX@{@}} just as the +node name does. + +For Info and HTML output, especially, it is necessary to expand +commands to some sequence of plain characters; for instance, +@code{@@TeX@{@}} expands to the three letters @samp{TeX} in the Info +node name. However, cross-references to the node should not take the +``shortcut'' of using @samp{TeX}; stick to the actual node name, +commands and all. + +Some commands do not make sense in node names; for instance, +environments (e.g., @code{@@quotation}), commands that read a whole +line as their argument (e.g., @code{@@sp}), and plenty of others. + +For the complete list of commands that are allowed, and their +expansion for HTML identifiers and file names, @pxref{HTML Xref +Command Expansion}. The expansions for Info are generally given with +main the description of the command. + +Prior to the Texinfo 5 release in 2013, this feature was supported in +an ad hoc way (the @option{--commands-in-node-names} option to +@command{makeinfo}). Now it is part of the language. + +@item +@cindex Colon in node name +@cindex Comma in node name +@cindex Parentheses in node name +@cindex Period in node name +@cindex Characters, invalid in node name +@cindex Invalid characters in node names +@cindex Node names, invalid characters in +Unfortunately, you cannot reliably use periods, commas, or colons +within a node name; these can confuse the Info reader. Also, a node +name may not start with a left parenthesis preceding a right +parenthesis, as in @code{(not)allowed}, since this syntax is used to +specify an external manual. (Perhaps these limitations will be +removed some day.) + +@command{makeinfo} warns about such problematic usage in node names, +menu items, and cross-references. If you don't want to see the +warnings, you can set the customization variable +@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other +Customization Variables}). + +Also, if you insist on using these characters in node names (accepting +the resulting substandard Info output), in order not to confuse the +Texinfo processors you must still escape those characters, by using +either special insertions (@pxref{Inserting a Comma}) or @code{@@asis} +(@pxref{@code{@@asis}}). For example: + +@example +@@node foo@@asis@{::@}bar +@end example + +As an example of avoiding the special characters, the following is a +section title in this manual: + +@smallexample +@@section @@code@{@@@@unnumbered@}, @@code@{@@@@appendix@}: ... +@end smallexample + +@noindent +But the corresponding node name lacks the commas and the subtitle: + +@smallexample +@@node @code{@@unnumbered @@appendix} +@end smallexample + +@cindex Case in node name +@item +Case is significant in node names. + +@cindex White space in node name +@cindex Spaces in node name +@item +Spaces before and after names on the @samp{@@node} line are ignored. +Multiple whitespace characters ``inside'' a name are collapsed to a +single space. For example: + +@example +@@node foo bar +@@node foo bar, +@@node foo bar , +@@node foo bar, +@@node foo bar , +@end example + +@noindent all define the same node, namely @samp{foo bar}. +In menu entries, this is the name that should be used: no leading or +trailing spaces, and a single internal space. (For cross-references, +the node name used in the Texinfo sources is automatically normalized +in this way.) + +@item +The next/previous/up pointers on @code{@@node} lines must be the names +of nodes. (It's recommended to leave out these explicit node pointer +names, which automatically avoids any problem here; @pxref{@command{makeinfo} +Pointer Creation}.) +@end itemize + + +@node First Node +@section The First Node +@cindex Top node is first +@cindex First node + +The first node of a Texinfo file is the @dfn{Top} node, except in an +included file (@pxref{Include Files}). The Top node should contain a +short summary, copying permissions, and a master menu. @xref{The Top +Node}, for more information on the Top node contents and examples. + +Here is a description of the node pointers to be used in the Top node: + +@itemize @bullet +@item +@cindex Up node of Top node +@cindex (dir) as Up node of Top node +The Top node (which must be named @samp{top} or @samp{Top}) should have +as its `Up' node the name of a node in another file, where there is a +menu that leads to this file. Specify the file name in parentheses. + +Usually, all Info files are available through a single virtual Info +tree, constructed from multiple directories. In this case, use +@samp{(dir)} as the parent of the Top node; this specifies the +top-level node in the @file{dir} file, which contains the main menu +for the Info system as a whole. (Each directory with Info files is +intended to contain a file named @file{dir}.) + +That's fine for Info, but for HTML output, one might well want the Up +link from the Top node to go somewhere other than @samp{dir.html}. +For example, for GNU the natural place would be +@url{http://www.gnu.org/manual/} (a web page collecting links to most +GNU manuals), better specified as just @code{/manual/} if the manual +will be installed on @code{www.gnu.org}. This can be specified with +the @code{TOP_NODE_UP_URL} customization variable (@pxref{HTML +Customization Variables}), as in + +@example +$ @kbd{makeinfo --html -c TOP_NODE_UP_URL=/manual/} ... +@end example + +All links to @code{(dir)} will be replaced by the given url. + +@item +@cindex Prev node of Top node +The `Prev' node of the Top node is usually either omitted or also set +to @file{(dir)}. Either is fine. + +@item +@cindex Next node of Top node +The `Next' node of the Top node should be the first chapter in your +document. + +@end itemize + +@xref{Installing an Info File}, for more information about installing +an Info file in the @file{info} directory. + +It is usually best to leave the pointers off entirely and let the +tools implicitly define them, with this simple result: + +@example +@@node Top +@end example + + +@node @code{@@top} Command +@section The @code{@@top} Sectioning Command + +@anchor{top command}@c old name +@anchor{makeinfo top}@c another old name +@anchor{makeinfo top command}@c yet another name +@findex top + +The @code{@@top} command is a special sectioning command that you +should only use after a @samp{@@node Top} line at the beginning of a +Texinfo file. The @code{@@top} command tells the @code{makeinfo} +formatter which node is to be used as the root of the node tree. + +It produces the same sort of output as @code{@@unnumbered} +(@pxref{@code{@@unnumbered @@appendix}}). + +The @code{@@top} node is conventionally wrapped in an +@code{@@ifnottex} conditional so that it will not appear in @TeX{} +output (@pxref{Conditionals}). +Thus, in practice, a Top node usually looks like this: + +@example +@@ifnottex +@@node Top +@@top @var{your-manual-title} + +@var{very-high-level-summary} +@@end ifnottex +@end example + +@code{@@top} is ignored when raising or lowering sections. That is, +it is never lowered and nothing can be raised to it +(@pxref{Raise/lower sections}). + + +@node Node Menu Illustration +@section Node and Menu Illustration + +Here is a diagram that illustrates a Texinfo file with three chapters, +each of which contains two sections. + +The ``root'' is at the top of the diagram and the ``leaves'' are at +the bottom. This is how such a diagram is drawn conventionally; it +illustrates an upside-down tree. For this reason, the root node is +called the `Top' node, and `Up' node pointers carry you closer to the +root. + +@example +@group + Top + | + ------------------------------------- + | | | + Chapter 1 Chapter 2 Chapter 3 + | | | + -------- -------- -------- + | | | | | | +Section Section Section Section Section Section + 1.1 1.2 2.1 2.2 3.1 3.2 +@end group +@end example + +Using explicit pointers (not recommended, but for shown for purposes +of the example), the fully-written command to start Chapter@tie{}2 +would be this: + +@example +@group +@@node Chapter 2, Chapter 3, Chapter 1, Top +@@comment node-name, next, previous, up +@end group +@end example + +@noindent +This @code{@@node} line says that the name of this node is +``Chapter@tie{}2'', the name of the `Next' node is ``Chapter 3'', the +name of the `Previous' node is ``Chapter@tie{}1'', and the name of the +`Up' node is ``Top''. You can (and should) omit writing out these +node names if your document is hierarchically organized +(@pxref{@command{makeinfo} Pointer Creation}), but the pointer +relationships still obtain. + +@quotation Note +`Next' and `Previous' refer to nodes at the @emph{same hierarchical +level} in the manual, not necessarily to the next node within the +Texinfo file. In the Texinfo file, the subsequent node may be at a +lower level---a section-level node most often follows a chapter-level +node, for example. (The `Top' node contains the exception to this +rule. Since the `Top' node is the only node at that level, `Next' +refers to the first following node, which is almost always a chapter +or chapter-level node.) +@end quotation + +To go to Sections 2.1 and 2.2 using Info, you need a menu inside +Chapter 2. (@xref{Menus}.) You would write the menu just before the +beginning of Section 2.1, like this: + +@example +@group + @@menu + * Sect. 2.1:: Description of this section. + * Sect. 2.2:: Description. + @@end menu +@end group +@end example + +Using explicit pointers, the node for Sect.@: 2.1 is written like this: + +@example +@group +@@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 +@@comment node-name, next, previous, up +@end group +@end example + +In Info format, the `Next' and `Previous' pointers of a node usually +lead to other nodes at the same level---from chapter to chapter or +from section to section (sometimes, as shown, the `Previous' pointer +points up); an `Up' pointer usually leads to a node at the level above +(closer to the `Top' node); and a `Menu' leads to nodes at a level +below (closer to `leaves'). (A cross-reference can point to a node at +any level; see @ref{Cross References}.) + +A @code{@@node} command and a chapter structuring command are +conventionally used together, in that order, often followed by +indexing commands. (As shown in the example above, you may follow the +@code{@@node} line with a comment line, e.g., to show which pointer is +which if explicit pointers are used.) The Texinfo processors use this +construct to determine the relationships between nodes and sectioning +commands. + +Here is the beginning of the chapter in this manual called ``Ending a +Texinfo File''. This shows an @code{@@node} line followed by an +@code{@@chapter} line, and then by indexing lines. + +@example +@group +@@node Ending a File +@@chapter Ending a Texinfo File +@@cindex Ending a Texinfo file +@@cindex Texinfo file ending +@@cindex File ending +@end group +@end example + +An earlier version of the manual used explicit node pointers. Here is +the beginning of the same chapter for that case. This shows an +@code{@@node} line followed by a comment line, a @code{@@chapter} +line, and then by indexing lines. + +@example +@group +@@node Ending a File, Structuring, Beginning a File, Top +@@comment node-name, next, previous, up +@@chapter Ending a Texinfo File +@@cindex Ending a Texinfo file +@dots{} +@end group +@end example + + +@node @command{makeinfo} Pointer Creation +@section @code{makeinfo} Pointer Creation + +@cindex Creating pointers with @code{makeinfo} +@cindex Pointer creation with @code{makeinfo} +@cindex Automatic pointer creation with @code{makeinfo} +@cindex Implicit pointer creation with @code{makeinfo} + +The @code{makeinfo} program can automatically determine node pointers +for a hierarchically organized document. This implicit node pointer +creation feature in @code{makeinfo} relieves you from the need to +update menus and pointers manually or with Texinfo mode commands. +(@xref{Updating Nodes and Menus}.) We highly recommend taking +advantage of this. + +To do so, write your @code{@@node} lines with just the name of the +node: + +@example +@@node My Node +@end example + +@noindent +You do not need to write out the `Next', `Previous', and `Up' +pointers. + +Then, you must write a sectioning command, such as @code{@@chapter} +or @code{@@section}, on the line immediately following each truncated +@code{@@node} line (except that comment lines may intervene). This is +where it normally goes. + +Also, you must write the name of each node (except for the `Top' node) +in a menu that is one or more hierarchical levels above the node's +level. + +Finally, you must follow the `Top' @code{@@node} line with a line +beginning with @code{@@top} to mark the top-level node in the file. +@xref{@code{@@top} Command}. + +@cindex Detail menu +@findex detailmenu +If you use a detailed menu in your master menu (@pxref{Master Menu +Parts}), mark it with the @code{@@detailmenu @dots{} @@end +detailmenu} environment, or @command{makeinfo} will get confused, +typically about the last and/or first node in the document. + +In most cases, you will want to take advantage of this feature and not +redundantly specify node pointers that the programs can determine. +However, Texinfo documents are not required to be organized +hierarchically or in fact to contain sectioning commands at all (for +example, if you never intend the document to be printed), so node +pointers may still be specified explicitly, in full generality. + + +@node Menus +@section Menus +@cindex Menus +@findex menu + +@dfn{Menus} contain pointers to subordinate nodes. In online output, +you use menus to go to such nodes. Menus have no effect in printed +manuals and do not appear in them. + +@menu +* Writing a Menu:: What is a menu? +* Menu Example:: Two and three part menu entries. +* Menu Location:: Menus go at the ends of nodes. +* Menu Parts:: A menu entry has three parts. +* Less Cluttered Menu Entry:: Two part menu entry. +* Other Info Files:: How to refer to a different Info file. +@end menu + + +@node Writing a Menu +@subsection Writing a Menu +@cindex Writing a menu +@cindex Menu writing + +A menu consists of a @code{@@menu} command on a line by itself, +followed by menu entry lines or menu comment lines, and then followed +by an @code{@@end menu} command on a line by itself. + +A menu looks like this: + +@example +@group +@@menu +Larger Units of Text + +* Files:: All about handling files. +* Multiples: Buffers. Multiple buffers; editing + several files at once. +@@end menu +@end group +@end example + +@cindex Spaces, in menus +In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu +entry}. (Note the space after the asterisk.) + +A line that does not start with an @w{@samp{* }} may also appear in a +menu. Such a line is not a menu entry but rather a @dfn{menu comment} +line that appears in the Info file. In the example above, the line +@samp{Larger Units of Text} is such a menu comment line; the two lines +starting with @w{@samp{* }} are menu entries. + +@cindex Hierarchical documents, and menus +Technically, menus can carry you to any node, regardless of the +structure of the document; even to nodes in a different Info file. +However, we do not recommend making use of this, because it is hard +for readers to follow. Also, the @command{makeinfo} implicit pointer +creation feature (@pxref{@command{makeinfo} Pointer Creation}) and GNU +Emacs Texinfo mode updating commands work only to create menus of +subordinate nodes in a hierarchically structured document. It is much +better to use cross-references to refer to arbitrary nodes. + +@cindex Menus, automatically generating +@findex validatemenus +@command{makeinfo} can automatically generate menus in nodes for Info +and HTML output, based on the chapter structure of the document. To +specify that you want it to do this, place the line +@samp{@@validatemenus off} near the beginning of the document. + +In Info, a user selects a node with the @kbd{m} (@code{Info-menu}) +command. The menu entry name is what the user types after the @kbd{m} +command. +@opindex accesskey@r{, in HTML output of menus} +In the HTML output from @command{makeinfo}, the @code{accesskey} +attribute is used with the values @samp{1}@dots{}@samp{9} for the +first nine entries. This allows people using web browsers to follow +the first menu entries using (typically) @kbd{M-@var{digit}}, e.g., +@kbd{M-1} for the first entry. + +@node Menu Example +@subsection A Menu Example +@cindex Menu example +@cindex Example menu + +@c merge with Writing a Menu node? + +A menu looks like this in Texinfo: + +@example +@group +@@menu +* menu entry name: Node name. A short description. +* Node name:: This form is preferred. +@@end menu +@end group +@end example + +@need 800 +@noindent +This produces: + +@example +@group +* menu: + +* menu entry name: Node name. A short description. +* Node name:: This form is preferred. +@end group +@end example + +@need 700 +Here is an example as you might see it in a Texinfo file: + +@example +@group +@@menu +Larger Units of Text + +* Files:: All about handling files. +* Multiples: Buffers. Multiple buffers; editing + several files at once. +@@end menu +@end group +@end example + +@need 800 +@noindent +This produces: + +@example +@group +* menu: +Larger Units of Text + +* Files:: All about handling files. +* Multiples: Buffers. Multiple buffers; editing + several files at once. +@end group +@end example + +In this example, the menu has two entries. @samp{Files} is both a menu +entry name and the name of the node referred to by that name. +@samp{Multiples} is the menu entry name; it refers to the node named +@samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it +appears in the menu, but is not an entry. + +Since no file name is specified with either @samp{Files} or +@samp{Buffers}, they must be the names of nodes in the same Info file +(@pxref{Other Info Files, , Referring to Other Info Files}). + + +@node Menu Location +@subsection Menu Location +@cindex Menu location +@cindex Location of menus + +There may be at most one menu in a node. A menu is conventionally +located at the end of a node, without any regular text or additional +commands between the @code{@@end menu} and the beginning of the next +node. + +@cindex Info format, and menus +This convention is useful, since a reader who uses the menu could +easily miss any such text. Also, any such post-menu text will be +considered part of the menu in Info output (which has no marker for +the end of a menu). Thus, a line beginning with @samp{* } will likely +be incorrectly handled. + +It's usually best if a node with a menu does not contain much text. +If you find yourself with a lot of text before a menu, we generally +recommend moving all but a couple of paragraphs into a new subnode. +Otherwise, it is easy for readers to miss the menu. + +@ignore +Years ago, we recommended using a @samp{@@heading} command within an +@code{@@ifinfo} conditional instead of the normal sectioning commands +after a very short node with a menu. This had the advantage of making +the printed output look better, because there was no very short text +between two headings on the page. But it does not work with +@command{makeinfo}'s implicit pointer creation, and it also makes the +XML output incorrect, since it does not reflect the true document +structure. So, we no longer recommend this. +@end ignore + + +@node Menu Parts +@subsection The Parts of a Menu +@cindex Parts of a menu +@cindex Menu parts +@cindex @code{@@menu} parts + +A menu entry has three parts, only the second of which is required: + +@enumerate +@item +The menu entry name (optional). + +@item +The name of the node (required). + +@item +A description of the item (optional). +@end enumerate + +The template for a generic menu entry looks like this (but see the +next section for one more possibility): + +@example +* @var{menu-entry-name}: @var{node-name}. @var{description} +@end example + +Follow the menu entry name with a single colon, and follow the node +name with tab, comma, newline, or the two characters period and space +(@samp{. }). + +The third part of a menu entry is a descriptive phrase or sentence. +Menu entry names and node names are often short; the description +explains to the reader what the node is about. A useful description +complements the node name rather than repeats it. The description, +which is optional, can spread over multiple lines; if it does, some +authors prefer to indent the second line while others prefer to align +it with the first (and all others). It's up to you. An empty line, +or the next menu entry, ends a description. + +Space characters in a menu are preserved as-is in the Info output; this +allows you to format the menu as you wish. Unfortunately you must type +node names without any extra spaces or some versions of some Info +readers will not find the node (@pxref{Node Line Requirements}). + + +@command{makeinfo} warns when the text of a menu item (and node names +and cross-references) contains a problematic construct that will +interfere with its parsing in Info. If you don't want to see the +warnings, you can set the customization variable +@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other +Customization Variables}). + + + +@node Less Cluttered Menu Entry +@subsection Less Cluttered Menu Entry +@cindex Two part menu entry +@cindex Double-colon menu entries +@cindex Menu entries with two colons +@cindex Less cluttered menu entry +@cindex Uncluttered menu entry + +When the menu entry name and node name are the same, you can write +the name immediately after the asterisk and space at the beginning of +the line and follow the name with two colons. + +@need 800 +For example, write + +@example +* Name:: @var{description} +@end example + +@need 800 +@noindent +instead of + +@example +* Name: Name. @var{description} +@end example + +We recommend using the node name for the menu entry name whenever +possible, since it reduces visual clutter in the menu. + + +@node Other Info Files +@subsection Referring to Other Info Files +@cindex Referring to other Info files +@cindex Nodes in other Info files +@cindex Other Info files' nodes +@cindex Going to other Info files' nodes +@cindex Info; other files' nodes + +You can create a menu entry that enables a reader in Info to go to a +node in another Info file by writing the file name in parentheses just +before the node name. Some examples: + +@example +@group +@@menu +* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description} +* (@var{filename})@var{second-node}:: @var{description} +@@end menu +@end group +@end example + +For example, to refer directly to the @samp{Outlining} and +@samp{Rebinding} nodes in the @cite{Emacs Manual}, you could write a +menu like this: + +@example +@group +@@menu +* Outlining: (emacs)Outline Mode. The major mode for + editing outlines. +* (emacs)Rebinding:: How to redefine the + meaning of a key. +@@end menu +@end group +@end example + +If you do not list the node name, but only name the file, then Info +presumes that you are referring to the `Top' node. Examples: + +@example +@group +* Info: (info). Documentation browsing system. +* (emacs):: The extensible, self-documenting + text editor. +@end group +@end example + +The GNU Emacs Texinfo mode menu updating commands only work with nodes +within the current buffer, so you cannot use them to create menus that +refer to other files. You must write such menus by hand. + + +@node Chapter Structuring +@chapter Chapter Structuring +@anchor{Structuring}@c old name +@cindex Chapter structuring +@cindex Structuring of chapters +@cindex Sectioning + +Texinfo's @dfn{chapter structuring} commands divide a document into a +hierarchy of chapters, sections, subsections, and subsubsections. These +commands generate large headings in the text, like the one above. They +also provide information for generating the table of contents +(@pxref{Contents,, Generating a Table of Contents}). + +Normally you put a @code{@@node} command immediately before each +chapter structuring command. @xref{Nodes}. + +@menu +* Tree Structuring:: A manual is like an upside down tree @dots{} +* Structuring Command Types:: How to divide a manual into parts. +* @code{@@chapter}:: Chapter structuring. +* @code{@@unnumbered @@appendix}:: +* @code{@@majorheading @@chapheading}:: +* @code{@@section}:: +* @code{@@unnumberedsec @@appendixsec @@heading}:: +* @code{@@subsection}:: +* @code{@@unnumberedsubsec @@appendixsubsec @@subheading}:: +* @code{@@subsubsection}:: Commands for the lowest level sections. +* @code{@@part}:: Collections of chapters. +* Raise/lower sections:: How to change commands' hierarchical level. +@end menu + + +@node Tree Structuring +@section Tree Structure of Sections +@cindex Tree structuring + +A Texinfo file is usually structured like a book with chapters, +sections, subsections, and the like. This structure can be visualized +as a tree (or rather as an upside-down tree) with the root at the top +and the levels corresponding to chapters, sections, subsection, and +subsubsections. + +Here is a diagram that shows a Texinfo file with three chapters, each +with two sections. + +@example +@group + Top + | + ------------------------------------- + | | | + Chapter 1 Chapter 2 Chapter 3 + | | | + -------- -------- -------- + | | | | | | +Section Section Section Section Section Section + 1.1 1.2 2.1 2.2 3.1 3.2 + +@end group +@end example + +In a Texinfo file that has this structure, the beginning of Chapter 2 +would be written like this: + +@example +@group +@@node Chapter 2 +@@chapter Chapter 2 +@end group +@end example + +@noindent +For purposes of example, here is how it would be written with +explicit node pointers: + +@example +@group +@@node Chapter 2, Chapter 3, Chapter 1, Top +@@chapter Chapter 2 +@end group +@end example + +The chapter structuring commands are described in the sections that +follow; the @code{@@node} command is described in +the previous chapter (@pxref{Nodes}). + + +@node Structuring Command Types +@section Structuring Command Types + +The chapter structuring commands fall into four groups or series, each +of which contains structuring commands corresponding to the +hierarchical levels of chapters, sections, subsections, and +subsubsections. + +The four groups of commands are the @code{@@chapter} series, the +@code{@@unnumbered} series, the @code{@@appendix} series, and the +@code{@@heading} series. Each command produces a title with a +different appearance in the body of the document. Some of the +commands list their titles in the tables of contents, while others do +not. Here are the details: + +@itemize @bullet +@item +The @code{@@chapter} and @code{@@appendix} series of commands produce +numbered or lettered entries both in the body of a document and in its +table of contents. + +@item +The @code{@@unnumbered} series of commands produce unnumbered entries +both in the body of a document and in its table of contents. The +@code{@@top} command, which has a special use, is a member of this +series (@pxref{@code{@@top} Command}). An @code{@@unnumbered} section +is a normal part of the document structure. + +@item +The @code{@@heading} series of commands produce simple unnumbered +headings that do not appear in a table of contents, are not associated +with nodes, and cannot be cross-referenced. These heading commands +never start a new page. +@end itemize + +When a @code{@@setchapternewpage} command says to do so, the +@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands +start new pages in the printed manual; the @code{@@heading} commands +do not. @xref{@code{@@setchapternewpage}}. + +Here is a summary: + +@tex +{\globaldefs=1 \smallfonts \rm} +@end tex + +@multitable @columnfractions .19 .30 .29 .22 +@item @tab @tab @tab No new page +@item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered} +@item In contents @tab In contents @tab In contents @tab Not in contents +@item @tab @code{@@top} @tab @tab @code{@@majorheading} +@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} @tab @code{@@chapheading} +@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading} +@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading} +@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading} +@end multitable +@tex +{\globaldefs=1 \textfonts \rm} +@end tex + + +@node @code{@@chapter} +@section @code{@@chapter}: Chapter Structuring + +@anchor{chapter}@c old name +@findex chapter + +@code{@@chapter} identifies a chapter in the document--the highest +level of the normal document structuring hierarchy. Write the command +at the beginning of a line and follow it on the same line by the title +of the chapter. The chapter is numbered automatically, starting +from@tie{}1. + +For example, the present chapter in this manual is entitled +``@code{@@chapter}: Chapter Structuring''; the @code{@@chapter} line +looks like this: + +@example +@@chapter @@code@{@@@@chapter@}: Chapter Structuring +@end example + +In @TeX{}, the @code{@@chapter} command produces a chapter heading in +the document. + +In Info and plain text output, the @code{@@chapter} command causes the +title to appear on a line by itself, with a line of asterisks inserted +underneath. So, the above example produces the following output: + +@example +@group +5 Chapter Structuring +********************* +@end group +@end example + +In HTML, the @code{@@chapter} command produces an @code{<h2>}-level +header by default (controlled by the @code{CHAPTER_HEADER_LEVEL} +customization variable, @pxref{Other Customization Variables}). + +In the XML and Docbook output, a @code{<chapter>} element is produced +that includes all the following sections, up to the next chapter. + + +@node @code{@@unnumbered @@appendix} +@section @code{@@unnumbered}, @code{@@appendix}: Chapters with Other Labeling + +@anchor{unnumbered & appendix}@c old name +@findex unnumbered +@findex appendix + +Use the @code{@@unnumbered} command to start a chapter-level element +that appears without chapter numbers of any kind. Use the +@code{@@appendix} command to start an appendix that is labeled by +letter (`A', `B', @dots{}) instead of by number; appendices are also +at the chapter level of structuring. + +Write an @code{@@appendix} or @code{@@unnumbered} command at the +beginning of a line and follow it on the same line by the title, +just as with @code{@@chapter}. + +@findex centerchap +Texinfo also provides a command @code{@@centerchap}, which is analogous +to @code{@@unnumbered}, but centers its argument in the printed and HTML +outputs. This kind of stylistic choice is not usually offered by +Texinfo. It may be suitable for short documents. +@c but the Hacker's Dictionary wanted it, before they quit Texinfo. + +@cindex Docbook and prefatory sections +@cindex Preface, etc., and Docbook +With @code{@@unnumbered}, if the name of the associated node is one of +these English words (case-insensitive): + +@example +Acknowledgements Colophon Dedication Preface +@end example + +@cindex @code{<acknowledgements>} Docbook tag +@cindex @code{<colophon>} Docbook tag +@cindex @code{<dedication>} Docbook tag +@cindex @code{<preface>} Docbook tag +@cindex @code{<chapter>} Docbook tag +@cindex @code{<title>} Docbook tag +@noindent then the Docbook output uses corresponding special tags +(@code{<preface>}, etc.)@: instead of the default @code{<chapter>}. +The argument to @code{@@unnumbered} itself can be anything, and is +output as the following @code{<title>} text as usual. + + +@node @code{@@majorheading @@chapheading} +@section @code{@@majorheading}, @code{@@chapheading}: Chapter-level Headings + +@anchor{majorheading & chapheading}@c old name +@findex majorheading +@findex chapheading + +The @code{@@majorheading} and @code{@@chapheading} commands produce +chapter-like headings in the body of a document. + +However, neither command produces an entry in the table of contents, +and neither command causes @TeX{} to start a new page in a printed +manual. + +In @TeX{}, a @code{@@majorheading} command generates a larger vertical +whitespace before the heading than a @code{@@chapheading} command but +is otherwise the same. + +In Info and plain text, the @code{@@majorheading} and +@code{@@chapheading} commands produce the same output as +@code{@@chapter}: the title is printed on a line by itself with a line +of asterisks underneath. Similarly for HTML@. The only difference is +the lack of numbering and the lack of any association with nodes. +@xref{@code{@@chapter}}. + + +@node @code{@@section} +@section @code{@@section}: Sections Below Chapters + +@anchor{section}@c old name +@findex section + +An @code{@@section} command identifies a section within a chapter +unit, whether created with @code{@@chapter}, @code{@@unnumbered}, or +@code{@@appendix}, following the numbering scheme of the chapter-level +command. Thus, within a @code{@@chapter} chapter numbered `1', the +sections are numbered `1.1', `1.2', etc.; within an @code{@@appendix} +``chapter'' labeled `A', the sections are numbered `A.1', `A.2', etc.; +within an @code{@@unnumbered} chapter, the section gets no number. +The output is underlined with @samp{=} in Info and plain text. + +To make a section, write the @code{@@section} command at the +beginning of a line and follow it on the same line by the section +title. For example, + +@example +@@section This is a section +@end example + +@noindent +might produce the following in Info: + +@example +@group +5.7 This is a section +===================== +@end group +@end example + +Section titles are listed in the table of contents. + +The @TeX{}, HTML, Docbook, and XML output is all analogous to the +chapter-level output, just ``one level down''; @pxref{@code{@@chapter}}. + + +@node @code{@@unnumberedsec @@appendixsec @@heading} +@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} + +@anchor{unnumberedsec appendixsec heading}@c old name +@findex unnumberedsec +@findex appendixsec +@findex heading + +The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading} +commands are, respectively, the unnumbered, appendix-like, and +heading-like equivalents of the @code{@@section} command (see the +previous section). + +@code{@@unnumberedsec} and @code{@@appendixsec} do not need to be used +in ordinary circumstances, because @code{@@section} may also be used +within @code{@@unnumbered} and @code{@@appendix} chapters; again, see +the previous section. + +@table @code +@item @@unnumberedsec +The @code{@@unnumberedsec} command may be used within an unnumbered +chapter or within a regular chapter or appendix to produce an +unnumbered section. + +@item @@appendixsec +@itemx @@appendixsection +@findex appendixsection +@findex appendixsec +@code{@@appendixsection} is a longer spelling of the +@code{@@appendixsec} command; the two are synonymous. + +Conventionally, the @code{@@appendixsec} or @code{@@appendixsection} +command is used only within appendices. + +@item @@heading +You may use the @code{@@heading} command (almost) anywhere for a +section-style heading that will not appear in the table of contents. +The @code{@@heading}-series commands can appear inside most +environments, for example, though pathological and useless locations +such as inside @code{@@titlepage}, as an argument to another command, +etc., are not allowed. + +@end table + + +@node @code{@@subsection} +@section @code{@@subsection}: Subsections Below Sections + +@anchor{subsection}@c old name +@findex subsection + +Subsections are to sections as sections are to chapters; +@pxref{@code{@@section}}. In Info and plain text, subsection titles +are underlined with @samp{-}. For example, + +@example +@@subsection This is a subsection +@end example + +@noindent +might produce + +@example +@group +1.2.3 This is a subsection +-------------------------- +@end group +@end example + +Subsection titles are listed in the table of contents. + +The @TeX{}, HTML, Docbook, and XML output is all analogous to the +chapter-level output, just ``two levels down''; +@pxref{@code{@@chapter}}. + + +@node @code{@@unnumberedsubsec @@appendixsubsec @@subheading} +@section The @code{@@subsection}-like Commands + +@anchor{unnumberedsubsec appendixsubsec subheading}@c old name +@findex unnumberedsubsec +@findex appendixsubsec +@findex subheading +@cindex Subsection-like commands + +The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and +@code{@@subheading} commands are, respectively, the unnumbered, +appendix-like, and heading-like equivalents of the @code{@@subsection} +command. (@xref{@code{@@subsection}}.) + +@code{@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to +be used in ordinary circumstances, because @code{@@subsection} may +also be used within sections of @code{@@unnumbered} and +@code{@@appendix} chapters (@pxref{@code{@@section}}). + +An @code{@@subheading} command produces a heading like that of a +subsection except that it is not numbered and does not appear in the +table of contents. Similarly, an @code{@@unnumberedsubsec} command +produces an unnumbered heading like that of a subsection and an +@code{@@appendixsubsec} command produces a subsection-like heading +labeled with a letter and numbers; both of these commands produce +headings that appear in the table of contents. In Info and plain +text, the @code{@@subsection}-like commands generate a title +underlined with hyphens. + + +@node @code{@@subsubsection} +@section @code{@@subsection} and Other Subsub Commands + +@anchor{subsubsection}@c old name +@findex subsubsection +@findex unnumberedsubsubsec +@findex appendixsubsubsec +@findex subsubheading +@cindex Subsub sectioning commands + +The fourth and lowest level sectioning commands in Texinfo are the +`subsub' commands. They are: + +@table @code +@item @@subsubsection +Subsubsections are to subsections as subsections are to sections. +(@xref{@code{@@subsection}}.) Subsubsection titles appear in the +table of contents. + +@item @@unnumberedsubsubsec +Unnumbered subsubsection titles appear in the table of contents, +but lack numbers. Otherwise, unnumbered subsubsections are the same +as subsubsections. + +@item @@appendixsubsubsec +Conventionally, appendix commands are used only for appendices and are +lettered and numbered appropriately. They also appear in the table +of contents. + +@item @@subsubheading +The @code{@@subsubheading} command may be used anywhere that you want +a small heading that will not appear in the table of contents. +@end table + +As with subsections, @code{@@unnumberedsubsubsec} and +@code{@@appendixsubsubsec} do not need to be used in ordinary +circumstances, because @code{@@subsubsection} may also be used within +subsections of @code{@@unnumbered} and @code{@@appendix} chapters +(@pxref{@code{@@section}}). + +In Info, `subsub' titles are underlined with periods. For example, + +@example +@@subsubsection This is a subsubsection +@end example + +@noindent +might produce + +@example +@group +1.2.3.4 This is a subsubsection +............................... +@end group +@end example + +The @TeX{}, HTML, Docbook, and XML output is all analogous to the +chapter-level output, just ``three levels down''; @pxref{@code{@@chapter}}. + + +@node @code{@@part} +@section @code{@@part}: Groups of Chapters +@findex part +@cindex Part pages + +The final sectioning command is @code{@@part}, to mark a @dfn{part} of +a manual, that is, a group of chapters or (rarely) appendices. This +behaves quite differently from the other sectioning commands, to fit +with the way such ``parts'' are conventionally used in books. + +No @code{@@node} command is associated with @code{@@part}. Just write +the command on a line by itself, including the part title, at the +place in the document you want to mark off as starting that part. For +example: + +@example +@@part Part I:@@* The beginning +@end example + +As can be inferred from this example, no automatic numbering or +labeling of the @code{@@part} text is done. The text is taken as-is. + +Because parts are not associated with nodes, no general text can +follow the @code{@@part} line. To produce the intended output, it +must be followed by a chapter-level command (including its node). +Thus, to continue the example: + +@example +@@part Part I:@@* The beginning + +@@node Introduction +@@chapter Introduction +... +@end example + +In the @TeX{} output, the @code{@@part} text is included in both the +normal and short tables of contents (@pxref{Contents}), without a page +number (since that is the normal convention). In addition, a ``part +page'' is output in the body of the document, with just the +@code{@@part} text. In the example above, the @code{@@*} causes a +line break on the part page (but is replaced with a space in the +tables of contents). This part page is always forced to be on an odd +(right-hand) page, regardless of the chapter pagination +(@pxref{@code{@@setchapternewpage}}). + +In the HTML output, the @code{@@part} text is similarly included in +the tables of contents, and a heading is included in the main document +text, as part of the following chapter or appendix node. + +In the XML and Docbook output, the @code{<part>} element includes all +the following chapters, up to the next @code{<part>}. A @code{<part>} +containing chapters is also closed at an appendix. + +In the Info and plain text output, @code{@@part} has no effect. + +@code{@@part} is ignored when raising or lowering sections (see next +section). That is, it is never lowered and nothing can be raised to it. + + +@node Raise/lower sections +@section Raise/lower Sections: @code{@@raisesections} and @code{@@lowersections} +@findex raisesections +@findex lowersections +@cindex Raising and lowering sections +@cindex Lowering and raising sections +@cindex Sections, raising and lowering + +The @code{@@raisesections} and @code{@@lowersections} commands +implicitly raise and lower the hierarchical level of following +chapters, sections and the other sectioning commands (excluding parts). + +That is, the @code{@@raisesections} command changes sections to +chapters, subsections to sections, and so on. Conversely, the +@code{@@lowersections} command changes chapters to sections, sections +to subsections, and so on. Thus, a @code{@@lowersections} command +cancels a @code{@@raisesections} command, and vice versa. + +@cindex Include files, and section levels +You can use @code{@@lowersections} to include text written as an outer +or standalone Texinfo file in another Texinfo file as an inner, +included file (@pxref{Include Files}). Typical usage looks like this: + +@example +@@lowersections +@@include somefile.texi +@@raisesections +@end example + +@noindent (Without the @code{@@raisesections}, all the subsequent +sections in the main file would also be lowered.) + +If the included file being lowered has a @code{@@top} node, you'll +need to conditionalize its inclusion with a flag (@pxref{@code{@@set +@@value}}). + +As a practical matter, you generally only want to raise or lower large +chunks, usually in external files as shown above. The final result has +to have menus that take the raising and lowering into account, so you +cannot just arbitrarily sprinkle @code{@@raisesections} and +@code{@@lowersections} commands throughout the document. + +Repeated use of the commands continues to raise or lower the +hierarchical level a step at a time. An attempt to raise above +`chapter' reproduces chapter commands; an attempt to lower below +`subsubsection' reproduces subsubsection commands. Also, lowered +subsubsections and raised chapters will not work with +@command{makeinfo}'s feature of implicitly determining node pointers, +since the menu structure cannot be represented correctly. + +Write each @code{@@raisesections} and @code{@@lowersections} command +on a line of its own. + + +@node Cross References +@chapter Cross-references +@cindex Making cross-references +@cindex Cross-references +@cindex References + +@dfn{Cross-references} are used to refer the reader to other parts of the +same or different Texinfo files. + +@menu +* References:: What cross-references are for. +* Cross Reference Commands:: A summary of the different commands. +* Cross Reference Parts:: A cross-reference has several parts. +* @code{@@xref}:: Begin a reference with `See' @dots{} +* Referring to a Manual as a Whole:: Refer to an entire manual. +* @code{@@ref}:: A reference for the last part of a sentence. +* @code{@@pxref}:: How to write a parenthetical cross-reference. +* @code{@@anchor}:: Defining arbitrary cross-reference targets +* @code{@@inforef}:: How to refer to an Info-only file. +* @code{@@url}:: How to refer to a uniform resource locator. +* @code{@@cite}:: How to refer to books not in the Info system. +@end menu + + +@node References +@section What References Are For + +Often, but not always, a printed document should be designed so that +it can be read sequentially. People tire of flipping back and forth +to find information that should be presented to them as they need +it. + +However, in any document, some information will be too detailed for +the current context, or incidental to it; use cross-references to +provide access to such information. Also, an online help system or a +reference manual is not like a novel; few read such documents in +sequence from beginning to end. Instead, people look up what they +need. For this reason, such creations should contain many cross +references to help readers find other information that they may not +have read. + +In a printed manual, a cross-reference results in a page reference, +unless it is to another manual altogether, in which case the +cross-reference names that manual. In Info, a cross-reference results +in an entry that you can follow using the Info @samp{f} command. +(@xref{Help-Xref,, Following cross-references, info, Info}.) In HTML, a +cross-reference results in an hyperlink. + +The various cross-reference commands use nodes (or anchors, +@pxref{@code{@@anchor}}) to define cross-reference locations. +@TeX{} needs nodes to define cross-reference locations. When @TeX{} +generates a DVI file, it records each node's page number and uses the +page numbers in making references. Thus, even if you are writing a +manual that will only be printed, and not used online, you must +nonetheless write @code{@@node} lines in order to name the places to +which you make cross-references. + +@need 800 +@node Cross Reference Commands +@section Different Cross-reference Commands +@cindex Different cross-reference commands + +There are three different cross-reference commands: + +@table @code +@item @@xref +Used to start a sentence in the printed manual and in HTML with +@w{`See @dots{}'} or an Info cross-reference saying @samp{*Note +@var{name}: @var{node}.}. + +@item @@ref +Used within or, more often, at the end of a sentence; produces just +the reference in the printed manual and in HTML without the preceding +`See' (same as @code{@@xref} for Info). + +@item @@pxref +Used within parentheses, at the end of a sentence, or otherwise before +punctuation, to make a reference. Its output starts with a lowercase +`see' in the printed manual and in HTML, and a lowercase @samp{*note} +in Info. (@samp{p} is for `parenthesis'.) +@end table + +Additionally, there are commands to produce references to documents +outside the Texinfo system. The @code{@@cite} command is used +to make references to books and manuals. @code{@@url} produces +a @acronym{URL}, for example a reference to a page on the World +Wide Web. @code{@@inforef} is used to make a reference to an Info +file for which there is no printed manual. + + +@node Cross Reference Parts +@section Parts of a Cross-reference +@cindex Cross-reference parts +@cindex Parts of a cross-reference +@anchor{Reference Syntax} @c merged node + +A cross-reference command requires only one argument, which is +the name of the node to which it refers. Here is a simple example: + +@example +@@xref@{Node name@}. +@end example + +@noindent +In Info output, this produces + +@example +*Note Node name::. +@end example + +@noindent +In a printed manual, the output is + +@quotation +See Section @var{nnn} [Node name], page @var{ppp}. +@end quotation + +A cross-reference command may contain up to four additional arguments. +By using these arguments, you can provide a cross-reference name, +a topic description or section title for the printed output, the name +of a different manual file, and the name of a different printed manual. +To refer to another manual as a whole, the manual file and/or the name +of the printed manual are the only required arguments (@pxref{Referring +to a Manual as a Whole}). + +@need 700 +Here is an example of a full five-part cross-reference: + +@example +@group +@@xref@{Node name, Online Label, Printed Label, +info-file-name, A Printed Manual@}, for details. +@end group +@end example + +@noindent +which produces + +@example +*Note Online Label: (info-file-name)Node name, +for details. +@end example + +@noindent +in Info and + +@quotation +See section ``Printed Label'' in @i{A Printed Manual}, for details. +@end quotation + +@noindent +in a printed book. + +The five possible arguments for a cross-reference are: + +@enumerate +@item +The node or anchor name (required, except for reference to whole +manuals). This is the location to which the cross-reference takes +you. In a printed document, the location of the node provides the +page reference only for references within the same document. +Use @code{@@node} to define the node (@pxref{Writing a Node}), or +@code{@@anchor} (@pxref{@code{@@anchor}}). + +Write a node name in a cross-reference in exactly the same way as in +the @code{@@node} line, including the same capitalization; otherwise, the +formatters may not find the reference. + +@item +A label for online output. It is usually omitted; then +the topic description (third argument) is used if it was specified; +if that was omitted as well, the node name is used. + +@item +A label for printed output. Often, this is the title or topic of the +section. This is used as the name of the reference in the printed +manual. If omitted, the node name is used. + +@item +The name of the manual file in which the reference is located, if it is +different from the current file. This name is used both for Info and +HTML. + +@item +The name of a printed manual from a different Texinfo file. +@end enumerate + +The template for a full five argument cross-reference looks like +this: + +@example +@group +@@xref@{@var{node-name}, @var{online-label}, @var{printed-label}, +@var{info-file-name}, @var{printed-manual-title}@} +@end group +@end example + +Whitespace before and after the commas separating these arguments is +ignored. To include a comma in one of the arguments, use +@code{@@comma@{@}} (@pxref{Inserting a Comma}). + +@cindex Comma after cross-reference +When processing with TeX, a comma is automatically inserted after the +page number for cross-references to within the same manual, unless the +closing brace of the argument is followed by non-whitespace (such as a +comma or period). This gives you the choice of whether to have a comma +there in Info or HTML output. For example, + +@example +@@xref@{Another Section@} for more information +@end example + +@noindent produces +@w{`See Another Section, page @var{ppp}, for more information'} in the +printed output, and +@w{@samp{*Note Another Section:: for more information}} in the Info +output. + +If an unwanted comma is added, follow the argument +with a command such as @samp{@@:}. For example, +@w{@samp{@@xref@{Hurricanes@}@@: --- for the details}} produces + +@quotation +See Hurricanes, page @var{ppp} --- for the details +@end quotation + +@noindent instead of +@w{`See Hurricanes, page @var{ppp}, --- for the details'}. + +Cross-references with one, two, three, four, and five arguments are +described separately following the description of @code{@@xref}. + +@command{makeinfo} warns when the text of a cross-reference (and node +names and menu items) contains a problematic construct that will +interfere with its parsing in Info. If you don't want to see the +warnings, you can set the customization variable +@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other +Customization Variables}). + + +@node @code{@@xref} +@section @code{@@xref} + +@anchor{xref}@c old name +@findex xref +@cindex Cross-references using @code{@@xref} +@cindex References using @code{@@xref} + +The @code{@@xref} command generates a cross-reference for the +beginning of a sentence. + +@menu +* One Argument:: @code{@@xref} with one argument. +* Two Arguments:: @code{@@xref} with two arguments. +* Three Arguments:: @code{@@xref} with three arguments. +* Four and Five Arguments:: @code{@@xref} with four and five arguments. +@end menu + +@node One Argument +@subsection @code{@@xref} with One Argument +@cindex One-argument form of cross-references + +The simplest form of @code{@@xref} takes one argument, the name of +another node in the same Texinfo file. + +@need 700 +@noindent +For example, + +@example +@@xref@{Tropical Storms@}. +@end example + +@noindent +produces + +@example +*Note Tropical Storms::. +@end example + +@noindent +in Info and + +@quotation +See Section 3.1 [Tropical Storms], page 24. +@end quotation + +@noindent +in a printed manual. + + +@node Two Arguments +@subsection @code{@@xref} with Two Arguments +@cindex Two-argument form of cross-references + +With two arguments, the second is used as a label for the online output. + +@need 750 +@noindent +The template is like this: + +@example +@@xref@{@var{node-name}, @var{online-label}@}. +@end example + +@need 700 +@noindent +For example, + +@example +@@xref@{Electrical Effects, Lightning@}. +@end example + +@noindent +produces: + +@example +*Note Lightning: Electrical Effects. +@end example + +@noindent +in Info and + +@quotation +See Section 5.2 [Electrical Effects], page 57. +@end quotation + +@noindent +in a printed manual, where the node name is printed. + +The second argument to cross-references must observe some of the +restrictions for node names (@pxref{Node Line Requirements}). The +most common issue is that colons cannot be used, since that interferes +with the parsing of the Info file. + + +@node Three Arguments +@subsection @code{@@xref} with Three Arguments +@cindex Three-argument form of cross-references + +A third argument replaces the node name in the @TeX{} output. The third +argument should be the name of the section in the printed output, or +else state the topic discussed by that section. + +@need 750 +@noindent +The template is like this: + +@example +@group +@@xref@{@var{node-name}, @var{online-label}, @var{printed-label}@}. +@end group +@end example + +@need 700 +@noindent +For example, + +@example +@group +@@xref@{Electrical Effects, Lightning, Thunder and Lightning@}, +for details. +@end group +@end example + +@noindent +produces + +@example +*Note Lightning: Electrical Effects, for details. +@end example + +@noindent +in Info and + +@quotation +See Section 5.2 [Thunder and Lightning], page 57, for details. +@end quotation + +@noindent +in a printed manual. + +If a third argument is given and the second one is empty, then the +third argument serves for both. (Note how two commas, side by side, mark +the empty second argument.) + +@example +@group +@@xref@{Electrical Effects, , Thunder and Lightning@}, +for details. +@end group +@end example + +@noindent +produces + +@example +*Note Thunder and Lightning: Electrical Effects, for details. +@end example + +@noindent +in Info and + +@quotation +See Section 5.2 [Thunder and Lightning], page 57, for details. +@end quotation + +@noindent +in a printed manual. + +The third argument to cross-references must observe some of the +restrictions for node names (@pxref{Node Line Requirements}). The +most common issue is that colons cannot be used, since that interferes +with the parsing of the Info file. + +As a practical matter, it is often best to write cross-references with +just the first argument if the node name and the section title are the +same (or nearly so), and with the first and third arguments only if the +node name and title are different. + +@findex xrefautomaticsectiontitle +Texinfo offers a setting to use the section title instead of node +names by default in cross-references (an explicitly specified third +argument still takes precedence): + +@example +@@xrefautomaticsectiontitle on +@end example + +Typically this line would be given near the beginning of the document +and used for the whole manual. But you can turn it off if you want +(@code{@@xrefautomaticsectiontitle off}), for example, if you're +including some other sub-document that doesn't have suitable section +names. + + +@node Four and Five Arguments +@subsection @code{@@xref} with Four and Five Arguments +@cindex Four- and five argument forms of cross-references + +In a cross-reference, a fourth argument specifies the name of another +Info file, different from the file in which the reference appears, and +a fifth argument specifies its title as a printed manual. + +@need 800 +@noindent +The full template is: + +@example +@group +@@xref@{@var{node-name}, @var{online-label}, @var{printed-label}, +@var{info-file-name}, @var{printed-manual-title}@}. +@end group +@end example + +@need 700 +@noindent +For example, + +@example +@@xref@{Electrical Effects, Lightning, Thunder and Lightning, +weather, An Introduction to Meteorology@}. +@end example + +@noindent +produces this output in Info: + +@example +*Note Lightning: (weather)Electrical Effects. +@end example + +@noindent +As you can see, the name of the Info file is enclosed in parentheses +and precedes the name of the node. + +@noindent +In a printed manual, the reference looks like this: + +@quotation +See section ``Thunder and Lightning'' in @cite{An Introduction to +Meteorology}. +@end quotation + +@noindent +The title of the printed manual is typeset like @code{@@cite}; and the +reference lacks a page number since @TeX{} cannot know to which page a +reference refers when that reference is to another manual. + +Next case: often, you will leave out the second argument when you use +the long version of @code{@@xref}. In this case, the third argument, +the topic description, will be used as the cross-reference name in +Info. For example, + +@example +@@xref@{Electrical Effects, , Thunder and Lightning, +weather, An Introduction to Meteorology@}. +@end example + +@noindent +produces + +@example +@group +*Note Thunder and Lightning: (weather)Electrical Effects. +@end group +@end example + +@noindent +in Info and + +@quotation +See section ``Thunder and Lightning'' in @cite{An Introduction to +Meteorology}. +@end quotation + +@noindent +in a printed manual. + +Next case: If the node name and the section title are the same in the +other manual, you may also leave out the section title. In this case, +the node name is used in both instances. For example, + +@example +@@xref@{Electrical Effects,,, +weather, An Introduction to Meteorology@}. +@end example + +@noindent +produces + +@example +@group +*Note (weather)Electrical Effects::. +@end group +@end example + +@noindent +in Info and + +@quotation +See section ``Electrical Effects'' in @cite{An Introduction to +Meteorology}. +@end quotation + +@noindent +in a printed manual. + +A very unusual case: you may want to refer to another manual file that +is within a single printed manual---when multiple Texinfo files are +incorporated into the same @TeX{} run but can create separate Info or +HTML output files. In this case, you need to specify only the fourth +argument, and not the fifth. + +Finally, it's also allowed to leave out all the arguments +@emph{except} the fourth and fifth, to refer to another manual as a +whole. See the next section. + + +@node Referring to a Manual as a Whole +@section Referring to a Manual as a Whole +@cindex Manual, referring to as a whole +@cindex Referring to an entire manual +@anchor{Top Node Naming} @c old name + +Ordinarily, you must always name a node in a cross-reference. +However, it's not unusual to want to refer to another manual as a +whole, rather than a particular section within it. In this case, +giving any section name is an unnecessary distraction. + +So, with cross-references to other manuals (@pxref{Four and Five +Arguments}), if the first argument is either @samp{Top} (capitalized +just that way) or omitted entirely, and the third argument is omitted, +the printed output includes no node or section name. (The Info output +includes @samp{Top} if it was given.) For example, + +@example +@@xref@{Top,,, make, The GNU Make Manual@}. +@end example + +@noindent produces + +@example +@group +*Note (make)Top::. +@end group +@end example + +@noindent and + +@quotation +See @cite{The GNU Make Manual}. +@end quotation + +@noindent +Info readers will go to the Top node of the manual whether +or not the `Top' node is explicitly specified. + +It's also possible (and is historical practice) to refer to a whole +manual by specifying the `Top' node and an appropriate entry for the +third argument to the @code{@@xref} command. Using this idiom, to +make a cross-reference to @cite{The GNU Make Manual}, you would write: + +@example +@@xref@{Top,, Overview, make, The GNU Make Manual@}. +@end example + +@noindent +which produces + +@example +*Note Overview: (make)Top. +@end example + +@noindent +in Info and + +@quotation +See section ``Overview'' in @cite{The GNU Make Manual}. +@end quotation + +@noindent +in a printed manual. + +In this example, @samp{Top} is the name of the first node, and +@samp{Overview} is the name of the first section of the manual. There +is no widely-used convention for naming the first section in a printed +manual, this is just what the Make manual happens to use. This +arbitrariness of the first name is a principal reason why omitting the +third argument in whole-manual cross-references is preferable. + + +@node @code{@@ref} +@section @code{@@ref} + +@anchor{ref}@c old name +@findex ref +@cindex Cross-references using @code{@@ref} +@cindex References using @code{@@ref} + +@code{@@ref} is nearly the same as @code{@@xref} except that it does +not generate a `See' in the printed output, just the reference itself. +This makes it useful as the last part of a sentence. + +@noindent For example, + +@cindex Hurricanes +@example +For more information, @@pxref@{This@}, and @@ref@{That@}. +@end example + +@noindent +produces in Info: + +@example +For more information, *note This::, and *note That::. +@end example + +@noindent +and in printed output: + +@quotation +For more information, see Section 1.1 [This], page 1, +and Section 1.2 [That], page 2. +@end quotation + +The @code{@@ref} command can tempt writers to express themselves in a +manner that is suitable for a printed manual but looks awkward in the +Info format. Bear in mind that your audience could be using both the +printed and the Info format. For example: + +@cindex Sea surges +@example +Sea surges are described in @@ref@{Hurricanes@}. +@end example + +@noindent +looks ok in the printed output: + +@quotation +Sea surges are described in Section 6.7 [Hurricanes], page 72. +@end quotation + +@noindent +but is awkward to read in Info, ``note'' being a verb: + +@example +Sea surges are described in *note Hurricanes::. +@end example + + +@node @code{@@pxref} +@section @code{@@pxref} + +@anchor{pxref}@c old name +@findex pxref +@cindex Cross-references using @code{@@pxref} +@cindex References using @code{@@pxref} + +The parenthetical reference command, @code{@@pxref}, is nearly the +same as @code{@@xref}, but it is best used within parentheses. +The command differs from @code{@@xref} in that @TeX{} typesets the +reference for the printed manual with a lowercase `see' rather than an +uppercase `See'. + +@noindent +With one argument, a parenthetical cross-reference looks like this: + +@cindex Flooding +@example +@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{} +@end example + +@need 800 +@noindent +which produces + +@example +@group +@dots{} storms cause flooding (*note Hurricanes::) @dots{} +@end group +@end example + +@noindent +in Info and + +@quotation +@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{} +@end quotation + +@noindent +in a printed manual. + +With two arguments, a parenthetical cross-reference has this template: + +@example +@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{} +@end example + +@noindent +which produces + +@example +@dots{} (*note @var{cross-reference-name}: @var{node-name}.) @dots{} +@end example + +@noindent +in Info and + +@quotation +@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{} +@end quotation + +@noindent +in a printed manual. + +@code{@@pxref} can be used with up to five arguments, just like +@code{@@xref} (@pxref{@code{@@xref}}). + +In past versions of Texinfo, it was not allowed to write punctuation +after a @code{@@pxref}, so it could be used @emph{only} before a +right parenthesis. This is no longer the case. +The effect of @samp{@@pxref@{@var{node-name}@}} is similar to that of +@samp{see @@ref@{@var{node-name}@}}. However, in many circumstance the +latter is preferrable, as this makes it clear in the Info output that +the word ``see'' should be present. + + +@node @code{@@anchor} +@section @code{@@anchor}: Defining Arbitrary Cross-reference Targets + +@anchor{anchor}@c old name +@findex anchor +@cindex Anchors +@cindex Cross-reference targets, arbitrary +@cindex Targets for cross-references, arbitrary + +An @dfn{anchor} is a position in your document, labelled so that +cross-references can refer to it, just as they can to nodes. You +create an anchor with the @code{@@anchor} command, and give the label +as a normal brace-delimited argument. For example: + +@example +This marks the @@anchor@{x-spot@}spot. +@dots{} +@@xref@{x-spot,,the spot@}. +@end example + +@noindent produces: + +@example +This marks the spot. +@dots{} +See [the spot], page 1. +@end example + +As you can see, the @code{@@anchor} command itself produces no output. +This example defines an anchor `x-spot' just before the word `spot'. +You can refer to it later with an @code{@@xref} or other cross +reference command, as shown (@pxref{Cross References}). + +It is best to put @code{@@anchor} commands just before the position you +wish to refer to; that way, the reader's eye is led on to the correct +text when they jump to the anchor. You can put the @code{@@anchor} +command on a line by itself if that helps readability of the source. +Whitespace (including newlines) is ignored after @code{@@anchor}. + +Anchor names and node names may not conflict. Anchors and nodes are +given similar treatment in some ways; for example, the +@code{goto-node} command takes either an anchor name or a node name as +an argument. (@xref{Go to node,,, info, Info}.) + +Also like node names, anchor names cannot include some characters +(@pxref{Node Line Requirements}). + +@cindex Nodes, deleting or renaming +Because of this duality, when you delete or rename a node, it is +usually a good idea to define an @code{@@anchor} with the old name. +That way, any links to the old node, whether from other Texinfo +manuals or general web pages, keep working. + + +@node @code{@@inforef} +@section @code{@@inforef}: Cross-references to Info-only Material + +@anchor{inforef}@c old name +@findex inforef +@cindex Cross-references using @code{@@inforef} +@cindex References using @code{@@inforef} + +@code{@@inforef} is used for making cross-references to Info +documents---even from a printed manual. This might be because you +want to refer to conditional @code{@@ifinfo} text +(@pxref{Conditionals}), or because printed output is not available +(perhaps because there is no Texinfo source), among other +possibilities. + +The command takes either two or three arguments, in the following +order: + +@enumerate +@item +The node name. + +@item +The cross-reference name (optional). + +@item +The Info file name. +@end enumerate + +@noindent +The template is: + +@example +@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@} +@end example + +@need 800 +@noindent +For example, + +@example +@group +@@inforef@{Advanced, Advanced Info commands, info@}, +for more information. +@end group +@end example + +@need 800 +@noindent +produces (in Info): + +@example +@group +*Note Advanced Info commands: (info)Advanced, +for more information. +@end group +@end example + +@need 800 +@noindent +and (in the printed output): + +@quotation +See Info file @file{info}, node @samp{Advanced}, for more information. +@end quotation + +(This particular example is not realistic, since the Info manual is +written in Texinfo, so all formats are available. In fact, we don't +know of any extant Info-only manuals.) + +The converse of @code{@@inforef} is @code{@@cite}, which is used to +refer to printed works for which no Info form exists. +@xref{@code{@@cite}}. + + +@node @code{@@url} +@section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} + +@anchor{uref}@c old name +@findex uref +@cindex Uniform resource locator, referring to +@cindex URL, referring to + +@cindex @code{href}, producing HTML +@code{@@uref} produces a reference to a uniform resource locator +(url). It takes one mandatory argument, the url, and two optional +arguments which control the text that is displayed. In HTML and PDF +output, @code{@@uref} produces a link you can follow. (To merely +indicate a url without creating a link people can follow, use +@code{@@indicateurl}, @pxref{@code{@@indicateurl}}.) + +@findex url +@anchor{url}@code{@@url} is a synonym for @code{@@uref}. +(Originally, @code{@@url} had the meaning of @code{@@indicateurl}, but +in practice it was almost always misused. So we've changed the +meaning.) + +The second argument, if specified, is the text to display (the default +is the url itself); in Info, DVI, and PDF output, but not in HTML +output, the url is output in addition to this text. + +@cindex Man page, reference to +The third argument, if specified, is the text to display, but in this +case the url is not output in any format. This is useful when the +text is already sufficiently referential, as in a man page. Also, if +the third argument is given, the second argument is ignored. + +@menu +* @code{@@url} Examples:: Examples of using all the forms of @code{@@url}. +* URL Line Breaking:: How lines are broken within @code{@@url} text. +* @code{@@url} PDF Output Format:: A special option to hide links in PDF output. +* PDF Colors:: Colorizing urls and other links in PDF output. +@end menu + + +@node @code{@@url} Examples +@subsection @code{@@url} Examples + +@cindex @code{@@url}, examples of using +@cindex URL, examples of displaying + +First, here is an example of the simplest form of @code{@@url}, with +just one argument. The given url is both the target and the visible +text of the link: + +@example +The official GNU ftp site is @@uref@{http://ftp.gnu.org/gnu@}. +@end example + +@noindent produces: +@display +The official GNU ftp site is @uref{http://ftp.gnu.org/gnu}. +@end display + +@subsubheading Two-argument form of @code{@@url} + +Here is an example of the two-argument form: +@example +The official @@uref@{http://ftp.gnu.org/gnu, GNU ftp site@} +holds programs and texts. +@end example + +@noindent which produces: +@display +The official @uref{http://ftp.gnu.org/gnu, GNU ftp site} +holds programs and texts. +@end display + +@noindent that is, the Info (and @TeX{}, etc.)@: output is this: +@example +The official GNU ftp site (http://ftp.gnu.org/gnu) +holds programs and texts. +@end example + +@noindent while the HTML output is this: +@example +The official <a href="http://ftp.gnu.org/gnu">GNU ftp site</a> +holds programs and texts. +@end example + +@subsubheading Three-argument form of @code{@@url} + +Finally, an example of the three-argument form: +@example +The @@uref@{/man.cgi/1/ls,,ls@} program @dots{} +@end example + +@noindent which, except for HTML, produces: +@display +The @uref{/man.cgi/1/ls,,ls} program @dots{} +@end display + +@noindent but with HTML: +@example +The <a href="/man.cgi/1/ls">ls</a> program @dots{} +@end example + + +By the way, some people prefer to display urls in the unambiguous +format: + +@display +<URL:http://@var{host}/@var{path}> +@end display + +@noindent +@cindex @code{<URL...>} convention, not used +You can use this form in the input file if you wish. We feel it's not +necessary to include the @samp{<URL:} and @samp{>} in the output, +since to be useful any software that tries to detect urls in text +already has to detect them without the @samp{<URL:}. + + +@node URL Line Breaking +@subsection URL Line Breaking + +@cindex Line breaking, and urls +@cindex Breakpoints within urls +@TeX{} allows line breaking within urls at only a few characters +(which are special in urls): @samp{&}, @samp{.}, @samp{#}, @samp{?}, +and @samp{/} (but not between two @samp{/} characters). A tiny amount +of stretchable space is also inserted around these characters to help +with line breaking. + +For HTML output, modern browsers will also do line breaking within +displayed urls. If you need to allow breaks at other characters you +can insert @code{@@/} as needed (@pxref{Line Breaks}). + +@findex urefbreakstyle +By default, in @TeX{} any such breaks at special characters will occur +after the character. Some people prefer such breaks to happen before +the special character. This can be controlled with the +@code{@@urefbreakstyle} command (this command has effect only in +@TeX{}): + +@example +@@urefbreakstyle @var{how} +@end example + +@noindent where the argument @var{how} is one of these words: + +@vindex after@r{, value for @code{@@urefbreakstyle}} +@vindex before@r{, value for @code{@@urefbreakstyle}} +@vindex none@r{, value for @code{@@urefbreakstyle}} +@table @samp +@item after +(the default) Potentially break after the special characters. +@item before +Potentially break before the special characters. +@item none +Do not consider breaking at the special characters at all; any potential +breaks must be manually inserted. +@end table + + +@node @code{@@url} PDF Output Format +@subsection @code{@@url} PDF Output Format + +@cindex PDF output of urls +@cindex URLs, PDF output of + +If the ultimate purpose of a PDF is only to be viewed online, perhaps +similar to HTML in some inchoate way, you may not want the urls to be +included in the visible text (just as urls are not visible to readers +of web pages). Texinfo provides a PDF-specific option for this, which +must be used inside @code{@@tex}: + +@findex \urefurlonlylinktrue +@example +@@tex +\global\urefurlonlylinktrue +@@end tex +@end example + +The result is that @code{@@url@{http://www.gnu.org, GNU@}} has the +visible output of just `GNU', with a link target of +@url{http://www.gnu.org}. Ordinarily, the visible output would +include both the label and the url: `GNU (@url{http://www.gnu.org})'. + +This option only has effect when the PDF output is produced with the +pdf@TeX{} program, not with other ways of getting from Texinfo to PDF +(e.g., @TeX{} to DVI to PDF)@. Consequently, it is ok to specify this +option unconditionally within @code{@@tex}, as shown above. It is +ignored when DVI is being produced. + + +@node PDF Colors +@subsection PDF Colors + +@cindex Colored links, in PDF output +@cindex Links, coloring in PDF output +@cindex URLs, coloring in PDF output + +By default, urls and cross-reference links are printed in black in PDF +output. Very occasionally, however, you may want to highlight such +``live'' links with a different color, as is commonly done on web +pages. Texinfo provides a PDF-specific option for specifying these +colors, which must be used inside @code{@@tex}: + +@findex \linkcolor +@findex \urlcolor +@example +@@tex +\global\def\linkcolor@{1 0 0@} % red +\global\def\urlcolor@{0 1 0@} % green +@@end tex +@end example + +@code{\urlcolor} changes the color of @code{@@url} output (both the +actual url and any textual label), while @code{\linkcolor} changes the +color for cross-references to nodes, etc. They are independent. + +@cindex RGB color specification. +The three given values must be numbers between 0 and 1, specifying the +amount of red, green, and blue respectively. + +These definitions only have an effect when the PDF output is produced +with the pdf@TeX{} program, not with other ways of getting from +Texinfo to PDF (e.g., @TeX{} to DVI to PDF)@. Consequently, it is ok +to specify this option unconditionally within @code{@@tex}, as shown +above. It is ignored when DVI is being produced. + +We do not recommend colorizing just for fun; unless you have a +specific reason to use colors, best to skip it. + + +@node @code{@@cite} +@section @code{@@cite}@{@var{reference}@} + +@anchor{cite}@c old name +@findex cite + +Use the @code{@@cite} command for the name of a book that lacks a +companion Info file. The command produces italics in the printed +manual, and quotation marks in the Info file. + +If a book is written in Texinfo, it is better to use a cross-reference +command since a reader can easily follow such a reference in Info. +@xref{@code{@@xref}}. + + +@node Marking Text +@chapter Marking Text, Words and Phrases +@cindex Paragraph, marking text within +@cindex Marking words and phrases +@cindex Words and phrases, marking them +@cindex Marking text within a paragraph +@cindex Text, marking up + +In Texinfo, you can mark words and phrases in a variety of ways. +The Texinfo formatters use this information to determine how to +highlight the text. +You can specify, for example, whether a word or phrase is a +defining occurrence, a metasyntactic variable, or a symbol used in a +program. Also, you can emphasize text, in several different ways. + +@menu +* Indicating:: How to indicate definitions, files, etc. +* Emphasis:: How to emphasize text. +@end menu + + +@node Indicating +@section Indicating Definitions, Commands, etc. + +@cindex Highlighting text +@cindex Indicating commands, definitions, etc. + +Texinfo has commands for indicating just what kind of object a piece +of text refers to. For example, email addresses are marked by +@code{@@email}; that way, the result can be a live link to send email +when the output format supports it. If the email address was simply +marked as ``print in a typewriter font'', that would not be possible. + +@menu +* Useful Highlighting:: Highlighting provides useful information. +* @code{@@code}:: Indicating program code. +* @code{@@kbd}:: Showing keyboard input. +* @code{@@key}:: Specifying keys. +* @code{@@samp}:: Indicating a literal sequence of characters. +* @code{@@verb}:: Indicating a verbatim sequence of characters. +* @code{@@var}:: Indicating metasyntactic variables. +* @code{@@env}:: Indicating environment variables. +* @code{@@file}:: Indicating file names. +* @code{@@command}:: Indicating command names. +* @code{@@option}:: Indicating option names. +* @code{@@dfn}:: Specifying definitions. +* @code{@@abbr}:: Indicating abbreviations. +* @code{@@acronym}:: Indicating acronyms. +* @code{@@indicateurl}:: Indicating an example url. +* @code{@@email}:: Indicating an electronic mail address. +@end menu + + +@node Useful Highlighting +@subsection Highlighting Commands are Useful + +The commands serve a variety of purposes: + +@table @code +@item @@code@{@var{sample-code}@} +Indicate text that is a literal example of a piece of a program. +@xref{@code{@@code}}. + +@item @@kbd@{@var{keyboard-characters}@} +Indicate keyboard input. @xref{@code{@@kbd}}. + +@item @@key@{@var{key-name}@} +Indicate the conventional name for a key on a keyboard. +@xref{@code{@@key}}. + +@item @@samp@{@var{text}@} +Indicate text that is a literal example of a sequence of characters. +@xref{@code{@@samp}}. + +@item @@verb@{@var{text}@} +Write a verbatim sequence of characters. +@xref{@code{@@verb}}. + +@item @@var@{@var{metasyntactic-variable}@} +Indicate a metasyntactic variable. @xref{@code{@@var}}. + +@item @@env@{@var{environment-variable}@} +Indicate an environment variable. @xref{@code{@@env}}. + +@item @@file@{@var{file-name}@} +Indicate the name of a file. @xref{@code{@@file}}. + +@item @@command@{@var{command-name}@} +Indicate the name of a command. +@xref{@code{@@command}}. + +@item @@option@{@var{option}@} +Indicate a command-line option. +@xref{@code{@@option}}. + +@item @@dfn@{@var{term}@} +Indicate the introductory or defining use of a term. +@xref{@code{@@dfn}}. + +@item @@cite@{@var{reference}@} +Indicate the name of a book. @xref{@code{@@cite}}. + +@item @@abbr@{@var{abbreviation}@} +Indicate an abbreviation, such as `Comput.'. + +@item @@acronym@{@var{acronym}@} +Indicate an acronym. @xref{@code{@@acronym}}. + +@item @@indicateurl@{@var{uniform-resource-locator}@} +Indicate an example (that is, nonfunctional) uniform resource locator. +@xref{@code{@@indicateurl}}. (Use @code{@@url} (@pxref{@code{@@url}}) for +live urls.) + +@item @@email@{@var{email-address}[, @var{displayed-text}]@} +Indicate an electronic mail address. @xref{@code{@@email}}. + +@end table + + +@node @code{@@code} +@subsection @code{@@code}@{@var{sample-code}@} + +@anchor{code}@c old name +@findex code + +@cindex Syntactic tokens, indicating +Use the @code{@@code} command to indicate text that is a piece of a +program and which consists of entire syntactic tokens. Enclose the +text in braces. + +@cindex Expressions in a program, indicating +@cindex Keywords, indicating +@cindex Reserved words, indicating +Thus, you should use @code{@@code} for an expression in a program, for +the name of a variable or function used in a program, or for a +keyword in a programming language. + +Use @code{@@code} for command names in languages that resemble +programming languages, such as Texinfo. For example, @code{@@code} and +@code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and +@samp{@@code@{@@@@samp@}} in the Texinfo source, respectively. + +@cindex Case, not altering in @code{@@code} +It is incorrect to alter the case of a word inside a @code{@@code} +command when it appears at the beginning of a sentence. Most computer +languages are case sensitive. In C, for example, @code{Printf} is +different from the identifier @code{printf}, and most likely is a +misspelling of it. Even in languages which are not case sensitive, it +is confusing to a human reader to see identifiers spelled in different +ways. Pick one spelling and always use that. If you do not want to +start a sentence with a command name written all in lowercase, you +should rearrange the sentence. + +In the Info output, @code{@@code} results in single quotation marks +around the text. In other formats, @code{@@code} argument is typeset +in a typewriter (monospace) font. For example, + +@example +The function returns @@code@{nil@}. +@end example + +@noindent +produces this: + +@quotation +The function returns @code{nil}. +@end quotation + +Here are some cases for which it is preferable @emph{not} to use @code{@@code}: + +@itemize @bullet +@item +For shell command names, such as @command{ls} (use @code{@@command}). + +@item +For environment variables, such as @env{TEXINPUTS} (use @code{@@env}). + +@item +For shell options, such as @samp{-c}, when such options stand alone (use +@code{@@option}). + +@item +An entire shell command often looks better if written using +@code{@@samp} rather than @code{@@code}. In this case, the rule is to +choose the more pleasing format. + +@item +For a string of characters shorter than a syntactic token. For example, +if you are writing about @samp{goto-ch}, which is just a part of the +name for the @code{goto-char} Emacs Lisp function, you should use +@code{@@samp}. + +@item +In general, when writing about the characters used in a token; for +example, do not use @code{@@code} when you are explaining what letters +or printable symbols can be used in the names of functions. (Use +@code{@@samp}.) Also, you should not use @code{@@code} to mark text +that is considered input to programs unless the input is written in a +language that is like a programming language. For example, you should +not use @code{@@code} for the keystroke commands of GNU Emacs (use +@code{@@kbd} instead) although you may use @code{@@code} for the names +of the Emacs Lisp functions that the keystroke commands invoke. + +@end itemize + +By default, @TeX{} will consider breaking lines at @samp{-} and +@samp{_} characters within @code{@@code} and related commands. This +can be controlled with @code{@@allowcodebreaks} +(@pxref{@code{@@allowcodebreaks}}). The HTML output attempts to +respect this for @samp{-}, but ultimately it is up to the browser's +behavior. For Info, it seems better never to make such breaks. + +For Info, the quotes are omitted in the output of the @code{@@code} +command and related commands (e.g., @code{@@kbd}, @code{@@command}), +in typewriter-like contexts such as the @code{@@example} environment +(@pxref{@code{@@example}}) and @code{@@code} itself, etc. + +To control which quoting characters are implicitly inserted by Texinfo +processors in the output of @samp{@@code}, etc., see the +@code{OPEN_QUOTE_SYMBOL} and @code{CLOSE_QUOTE_SYMBOL} customization +variables (@pxref{Other Customization Variables}). This is separate +from how actual quotation characters in the input document are handled +(@pxref{Inserting Quote Characters}). + + +@node @code{@@kbd} +@subsection @code{@@kbd}@{@var{keyboard-characters}@} + +@anchor{kbd}@c old name +@findex kbd +@cindex Keyboard input + +Use the @code{@@kbd} command for characters of input to be typed by +users. For example, to refer to the characters @kbd{M-a}, write: + +@example +@@kbd@{M-a@} +@end example + +@noindent +and to refer to the characters @kbd{M-x shell}, write: + +@example +@@kbd@{M-x shell@} +@end example + +@cindex User input +@cindex Slanted typewriter font, for @code{@@kbd} +By default, the @code{@@kbd} command produces a different font +(slanted typewriter instead of normal typewriter), +so users can distinguish the characters that they are supposed +to type from those that the computer outputs. + +@findex kbdinputstyle +Since the usage of @code{@@kbd} varies from manual to manual, you can +control the font switching with the @code{@@kbdinputstyle} command. +This command has no effect on Info output. Write this command at the +beginning of a line with a single word as an argument, one of the +following: + +@vindex distinct@r{, value for @code{@@kbdinputstyle}} +@vindex example@r{, value for @code{@@kbdinputstyle}} +@vindex code@r{, value for @code{@@kbdinputstyle}} +@table @samp +@item code +Always use the same font for @code{@@kbd} as @code{@@code}. +@item example +Use the distinguishing font for @code{@@kbd} only in @code{@@example} +and similar environments. +@item distinct +(the default) Always use the distinguishing font for @code{@@kbd}. +@end table + +You can embed another @@-command inside the braces of a @code{@@kbd} +command. Here, for example, is the way to describe a command that +would be described more verbosely as ``press the @samp{r} key and then +press the @key{RETURN} key'': + +@example +@@kbd@{r @@key@{RET@}@} +@end example + +@noindent +This produces: @kbd{r @key{RET}}. (The present manual uses the +default for @code{@@kbdinputstyle}.) + +You also use the @code{@@kbd} command if you are spelling out the letters +you type; for example: + +@example +To give the @@code@{logout@} command, +type the characters @@kbd@{l o g o u t @@key@{RET@}@}. +@end example + +@noindent +This produces: + +@quotation +To give the @code{logout} command, +type the characters @kbd{l o g o u t @key{RET}}. +@end quotation + +(Also, this example shows that you can add spaces for clarity. If you +explicitly want to mention a space character as one of the characters of +input, write @kbd{@@key@{SPC@}} for it.) + + +@node @code{@@key} +@subsection @code{@@key}@{@var{key-name}@} + +@anchor{key}@c old name +@findex key + +Use the @code{@@key} command for the conventional name for a key on a +keyboard, as in: + +@example +@@key@{RET@} +@end example + +You can use the @code{@@key} command within the argument of an +@code{@@kbd} command when the sequence of characters to be typed +includes one or more keys that are described by name. + +For example, to produce @kbd{C-x @key{ESC}} and @kbd{M-@key{TAB}} you +would type: + +@example +@@kbd@{C-x @@key@{ESC@}@} +@@kbd@{M-@@key@{TAB@}@} +@end example + +Here is a list of the recommended names for keys: +@cindex Recommended names for keys +@cindex Keys, recommended names +@cindex Names recommended for keys +@cindex Abbreviations for keys +@cindex Control keys, specifying +@cindex Meta keys, specifying + +@quotation +@table @t +@item SPC +Space +@item RET +Return +@item LFD +Linefeed (however, since most keyboards nowadays do not have a Linefeed key, +it might be better to call this character @kbd{C-j}) +@item TAB +Tab +@item BS +Backspace +@item ESC +Escape +@item DELETE +Delete +@item SHIFT +Shift +@item CTRL +Control +@item META +Meta +@end table +@end quotation + +@cindex META key +There are subtleties to handling words like `meta' or `ctrl' that are +names of modifier keys. When mentioning a character in which the +modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command +alone; do not use the @code{@@key} command; but when you are referring +to the modifier key in isolation, use the @code{@@key} command. For +example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and +@samp{@@key@{META@}} to produce @key{META}. + +@c per rms. +As a convention in GNU manuals, @code{@@key} should not be used in +index entries. + + +@node @code{@@samp} +@subsection @code{@@samp}@{@var{text}@} + +@anchor{samp}@c old name +@findex samp + +Use the @code{@@samp} command to indicate text that is a literal example +or `sample' of a sequence of characters in a file, string, pattern, etc. +Enclose the text in braces. The argument appears within single +quotation marks in both the Info file and the printed manual; in +addition, it is printed in a fixed-width font. + +@example +To match @@samp@{foo@} at the end of the line, +use the regexp @@samp@{foo$@}. +@end example + +@noindent +produces + +@quotation +To match @samp{foo} at the end of the line, use the regexp +@samp{foo$}. +@end quotation + +Any time you are referring to single characters, you should use +@code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate. +Also, you may use @code{@@samp} for entire statements in C and for entire +shell commands---in this case, @code{@@samp} often looks better than +@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is +not covered by @code{@@code}, @code{@@kbd}, @code{@@key}, +@code{@@command}, etc. + +Only include punctuation marks within braces if they are part of the +string you are specifying. Write punctuation marks outside the braces +if those punctuation marks are part of the English text that surrounds +the string. In the following sentence, for example, the commas and +period are outside of the braces: + +@example +@group +In English, the vowels are @@samp@{a@}, @@samp@{e@}, +@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes +@@samp@{y@}. +@end group +@end example + +@noindent +This produces: + +@quotation +In English, the vowels are @samp{a}, @samp{e}, +@samp{i}, @samp{o}, @samp{u}, and sometimes +@samp{y}. +@end quotation + + +@node @code{@@verb} +@subsection @code{@@verb}@{@var{char}@var{text}@var{char}@} + +@anchor{verb}@c old name +@findex verb +@cindex Verbatim in-line text + +@cindex Delimiter character, for verbatim +Use the @code{@@verb} command to print a verbatim sequence of +characters. + +Like @LaTeX{}'s @code{\verb} command, the verbatim text can be quoted using +any unique delimiter character. Enclose the verbatim text, including the +delimiters, in braces. Text is printed in a fixed-width font: + +@example +How many @@verb@{|@@|@}-escapes does one need to print this +@@verb@{.@@a @@b.@@c.@} string or @@verb@{+@@'e?`@{@}!`\+@} this? +@end example + +@noindent +produces + +@example +How many @verb{|@|}-escapes does one need to print this +@verb{.@a @b.@c.} string or @verb{+@'e?`{}!`\+} this? +@end example + +This is in contrast to @code{@@samp} (see the previous section), +@code{@@code}, and similar commands; in those cases, the argument is +normal Texinfo text, where the three characters @code{@@@{@}} are +special, as usual. With @code{@@verb}, nothing is special except the +delimiter character you choose. + +The delimiter character itself may appear inside the verbatim text, as +shown above. As another example, @samp{@@verb@{...@}} prints a single +(fixed-width) period. + +It is not reliable to use @code{@@verb} inside other Texinfo +constructs. In particular, it does not work to use @code{@@verb} in +anything related to cross-referencing, such as section titles or +figure captions. + + +@node @code{@@var} +@subsection @code{@@var}@{@var{metasyntactic-variable}@} + +@anchor{var}@c old name +@findex var + +Use the @code{@@var} command to indicate metasyntactic variables. A +@dfn{metasyntactic variable} is something that stands for another +piece of text. For example, you should use a metasyntactic variable +in the documentation of a function to describe the arguments that are +passed to that function. + +Do not use @code{@@var} for the names of normal variables in computer +programs. These are specific names, so @code{@@code} is correct for +them (@code{@@code}). For example, the Emacs Lisp variable +@code{texinfo-tex-command} is not a metasyntactic variable; it is +properly formatted using @code{@@code}. + +Do not use @code{@@var} for environment variables either; @code{@@env} +is correct for them (see the next section). + +The effect of @code{@@var} in the Info file is to change the case of +the argument to all uppercase. In the printed manual and HTML +output, the argument is output in slanted type. + +@need 700 +For example, + +@example +To delete file @@var@{filename@}, +type @@samp@{rm @@var@{filename@}@}. +@end example + +@noindent +produces + +@quotation +To delete file @var{filename}, type @samp{rm @var{filename}}. +@end quotation + +@noindent +(Note that @code{@@var} may appear inside @code{@@code}, +@code{@@samp}, @code{@@file}, etc.) + +Write a metasyntactic variable all in lowercase without spaces, and +use hyphens to make it more readable. Thus, the Texinfo source for +the illustration of how to begin a Texinfo manual looks like +this: + +@example +@group +\input texinfo +@@@@settitle @@var@{name-of-manual@} +@end group +@end example + +@noindent +This produces: + +@example +@group +\input texinfo +@@settitle @var{name-of-manual} +@end group +@end example + +In some documentation styles, metasyntactic variables are shown with +angle brackets, for example: + +@example +@dots{}, type rm <filename> +@end example + +@noindent +However, that is not the style that Texinfo uses. + +@c FIXME add a customization variable? Add an example on how to do that +@c for HTML? +@c (You can, of course, modify the sources to @file{texinfo.tex} +@c and the Info formatting commands +@c to output the @code{<@dots{}>} format if you wish.) + + +@node @code{@@env} +@subsection @code{@@env}@{@var{environment-variable}@} + +@anchor{env}@c old name +@findex env + +Use the @code{@@env} command to indicate environment variables, as +used by many operating systems, including GNU@. Do not use it for +@emph{meta}syntactic variables; use @code{@@var} for those (see the +previous section). + +@code{@@env} is equivalent to @code{@@code} in its effects. +For example: + +@example +The @@env@{PATH@} environment variable @dots{} +@end example +@noindent produces +@quotation +The @env{PATH} environment variable @dots{} +@end quotation + + +@node @code{@@file} +@subsection @code{@@file}@{@var{file-name}@} + +@anchor{file}@c old name +@findex file + +Use the @code{@@file} command to indicate text that is the name of a +file, buffer, or directory, or is the name of a node in Info. You can +also use the command for file name suffixes. Do not use @code{@@file} +for symbols in a programming language; use @code{@@code}. + +@code{@@file} is equivalent to @code{code} in its effects. For +example, + +@example +The @@file@{.el@} files are in +the @@file@{/usr/local/emacs/lisp@} directory. +@end example + +@noindent +produces + +@quotation +The @file{.el} files are in +the @file{/usr/local/emacs/lisp} directory. +@end quotation + + +@node @code{@@command} +@subsection @code{@@command}@{@var{command-name}@} + +@anchor{command}@c old name +@findex command +@cindex Command names, indicating +@cindex Program names, indicating + +Use the @code{@@command} command to indicate command names, such as +@command{ls} or @command{cc}. + +@code{@@command} is equivalent to @code{@@code} in its effects. +For example: + +@example +The command @@command@{ls@} lists directory contents. +@end example +@noindent produces +@quotation +The command @command{ls} lists directory contents. +@end quotation + +You should write the name of a program in the ordinary text font, rather +than using @code{@@command}, if you regard it as a new English word, +such as `Emacs' or `Bison'. + +When writing an entire shell command invocation, as in @samp{ls -l}, +you should use either @code{@@samp} or @code{@@code} at your discretion. + + +@node @code{@@option} +@subsection @code{@@option}@{@var{option-name}@} + +@anchor{option}@c old name +@findex option + +Use the @code{@@option} command to indicate a command-line option; for +example, @option{-l} or @option{--version} or +@option{--output=@var{filename}}. + +@code{@@option} is equivalent to @code{@@code} in its effects. +For example: + +@example +The option @@option@{-l@} produces a long listing. +@end example +@noindent produces +@quotation +The option @option{-l} produces a long listing. +@end quotation + + +@node @code{@@dfn} +@subsection @code{@@dfn}@{@var{term}@} + +@anchor{dfn}@c old name +@findex dfn + +Use the @code{@@dfn} command to identify the introductory or defining +use of a technical term. Use the command only in passages whose +purpose is to introduce a term which will be used again or which the +reader ought to know. Mere passing mention of a term for the first +time does not deserve @code{@@dfn}. The command generates italics in +the printed manual, and double quotation marks in the Info file. For +example: + +@example +Getting rid of a file is called @@dfn@{deleting@} it. +@end example + +@noindent +produces + +@quotation +Getting rid of a file is called @dfn{deleting} it. +@end quotation + +As a general rule, a sentence containing the defining occurrence of a +term should be a definition of the term. The sentence does not need +to say explicitly that it is a definition, but it should contain the +information of a definition---it should make the meaning clear. + + +@node @code{@@abbr} +@subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@} + +@anchor{abbr}@c old name +@findex abbr + +@cindex Abbreviations, tagging +You can use the @code{@@abbr} command for general abbreviations. The +abbreviation is given as the single argument in braces, as in +@samp{@@abbr@{Comput.@}}. As a matter of style, or for particular +abbreviations, you may prefer to omit periods, as in +@samp{@@abbr@{Mr@} Stallman}. + +@code{@@abbr} accepts an optional second argument, intended to be used +for the meaning of the abbreviation. + +If the abbreviation ends with a lowercase letter and a period, and is +not at the end of a sentence, and has no second argument, remember to +use the @code{@@.} command (@pxref{Ending a Sentence}) to get the +correct spacing. However, you do not have to use @code{@@.} within +the abbreviation itself; Texinfo automatically assumes periods within +the abbreviation do not end a sentence. + +@cindex @code{<abbr>} and @code{<abbrev>} tags +In @TeX{} and in the Info output, the first argument is printed as-is; +if the second argument is present, it is printed in parentheses after +the abbreviation. In HTML the @code{<abbr>} tag is used; in Docbook, +the @code{<abbrev>} tag is used. For instance: + +@example +@@abbr@{Comput. J., Computer Journal@} +@end example + +@noindent produces: + +@display +@abbr{Comput. J., Computer Journal} +@end display + +For abbreviations consisting of all capital letters, you may prefer to +use the @code{@@acronym} command instead. See the next section for +more on the usage of these two commands. + + +@node @code{@@acronym} +@subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@} + +@anchor{acronym}@c old name +@findex acronym + +@cindex NASA, as acronym +@cindex Acronyms, tagging +You can use the @code{@@acronym} command for abbreviations written in +all capital letters, such as `@acronym{NASA}'. The abbreviation is +given as the single argument in braces, as in +@samp{@@acronym@{NASA@}}. As a matter of style, or for particular +acronyms, you may prefer to use periods, as in +@samp{@@acronym@{N.A.S.A.@}}. + +@code{@@acronym} accepts an optional second argument, intended to be +used for the meaning of the acronym. + +If the acronym is at the end of a sentence, and if there is no second +argument, remember to use the @code{@@.} or similar command +(@pxref{Ending a Sentence}) to get the correct spacing. + +@cindex @code{<acronym>} tag +In @TeX{}, the acronym is printed in slightly smaller font. In the +Info output, the argument is printed as-is. In either format, if the +second argument is present, it is printed in parentheses after the +acronym. In HTML and Docbook the @code{<acronym>} tag is used. + +For instance (since GNU is a recursive acronym, we use +@code{@@acronym} recursively): + +@example +@@acronym@{GNU, @@acronym@{GNU@}'s Not Unix@} +@end example + +@noindent produces: + +@display +@acronym{GNU, @acronym{GNU}'s Not Unix} +@end display + +@cindex Family names, in all capitals +In some circumstances, it is conventional to print family names in all +capitals. Don't use @code{@@acronym} for this, since a name is not an +acronym. Use @code{@@sc} instead (@pxref{Smallcaps}). + +@code{@@abbr} and @code{@@acronym} are closely related commands: they +both signal to the reader that a shortened form is being used, and +possibly give a meaning. When choosing whether to use these two +commands, please bear the following in mind. + +@itemize @minus +@item +In common English usage, acronyms are a subset of abbreviations: they +include pronounceable words like `@acronym{NATO}', `radar', and +`snafu'; some sources also include syllable acronyms like +`Usenet', hybrids like `@acronym{SIGGRAPH}', and unpronounceable +initialisms like `@acronym{FBI}'. + +@item +In Texinfo, an acronym (but not an abbreviation) should consist only +of capital letters and periods, no lowercase. + +@item +In @TeX{}, an acronym (but not an abbreviation) is printed in a +slightly smaller font. + +@item +Some browsers place a dotted bottom border under abbreviations but not +acronyms. + +@item +It usually turns out to be quite difficult and/or time-consuming to +consistently use @code{@@acronym} for all sequences of uppercase +letters. Furthermore, it looks strange for some acronyms to be in the +normal font size and others to be smaller. Thus, a simpler approach +you may wish to consider is to avoid @code{@@acronym} and just typeset +everything as normal text in all capitals: @samp{GNU}, producing the +output `GNU'. + +@item +In general, it's not essential to use either of these commands for all +abbreviations; use your judgment. Text is perfectly readable without +them. +@end itemize + + +@node @code{@@indicateurl} +@subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@} + +@anchor{indicateurl}@c old name +@findex indicateurl +@cindex Uniform resource locator, indicating +@cindex URL, indicating + +Use the @code{@@indicateurl} command to indicate a uniform resource +locator on the World Wide Web. This is purely for markup purposes and +does not produce a link you can follow (use the @code{@@url} or +@code{@@uref} command for that, @pxref{@code{@@url}}). +@code{@@indicateurl} is useful for urls which do not actually exist. +For example: + +@example +For example, the url might be @@indicateurl@{http://example.org/path@}. +@end example + +@noindent which produces: + +@display +For example, the url might be @indicateurl{http://example.org/path}. +@end display + +The output from @code{@@indicateurl} is more or less like that of +@code{@@samp} (@pxref{@code{@@samp}}). + + +@node @code{@@email} +@subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@} + +@anchor{email}@c old name +@findex email + +Use the @code{@@email} command to indicate an electronic mail address. +It takes one mandatory argument, the address, and one optional argument, the +text to display (the default is the address itself). + +@cindex Mailto link +In Info, the address is shown in angle brackets, preceded by the text +to display if any. In @TeX{}, the angle brackets are omitted. In +HTML output, @code{@@email} produces a @samp{mailto} link that usually +brings up a mail composition window. For example: + +@example +Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}, +suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. +@end example + +@noindent produces + +@display +Send bug reports to @email{bug-texinfo@@gnu.org}, +suggestions to the @email{bug-texinfo@@gnu.org, same place}. +@end display + + +@node Emphasis +@section Emphasizing Text +@cindex Emphasizing text + +Usually, Texinfo changes the font to mark words in the text according +to the category the words belong to; an example is the @code{@@code} +command. Most often, this is the best way to mark words. However, +sometimes you will want to emphasize text without indicating a +category. Texinfo has two commands to do this. Also, Texinfo has +several commands that specify the font in which text will be output. +These commands have no effect in Info and only one of them, the +@code{@@r} command, has any regular use. + +@menu +* @code{@@emph @@strong}:: How to emphasize text in Texinfo. +* Smallcaps:: How to use the small caps font. +* Fonts:: Various font commands for printed output. +@end menu + + +@node @code{@@emph @@strong} +@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} + +@anchor{emph & strong}@c oldname +@findex emph +@findex strong +@cindex Emphasizing text, font for + +The @code{@@emph} and @code{@@strong} commands are for emphasis; +@code{@@strong} is stronger. In printed output, @code{@@emph} produces +@emph{italics} and @code{@@strong} produces @strong{bold}. +In the Info output, @code{@@emph} surrounds the text with underscores +(@samp{_}), and @code{@@strong} puts asterisks around the text. + +For example, + +@example +@group +@@strong@{Caution:@} @@samp@{rm * .[^.]*@} +removes @@emph@{all@} files in the directory. +@end group +@end example + +@noindent +produces the following: + +@quotation +@strong{Caution}: @samp{rm * .[^.]*} +removes @emph{all} files in the directory. +@end quotation + +The @code{@@strong} command is seldom used except to mark what is, in +effect, a typographical element, such as the word `Caution' in the +preceding example. + +@quotation Caution +Do not use @code{@@strong} with the word @samp{Note} followed by a +space; Info will mistake the combination for a cross-reference. Use a +phrase such as @strong{Please notice} or @strong{Caution} instead, or +the optional argument to @code{@@quotation}---@samp{Note} is allowable +there. +@end quotation + + +@node Smallcaps +@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font +@cindex Small caps font +@findex sc @r{(small caps font)} + +Use the @samp{@@sc} command to set text in @sc{a small caps font} +(where possible). Write the text you want to be in small caps between +braces in lowercase, like this: + +@example +Richard @@sc@{Stallman@} commenc@'{e} GNU. +@end example + +@noindent +This produces: + +@display +Richard @sc{Stallman} commenc@'{e} GNU. +@end display + +As shown here, we recommend reserving @code{@@sc} for special cases +where you want typographic small caps; family names are one such, +especially in languages other than English, though there are no +hard-and-fast rules about such things. + +@cindex @code{<small>} tag +@TeX{} typesets any uppercase letters between the braces of an +@code{@@sc} command in full-size capitals; only lowercase letters are +printed in the small caps font. In the Info output, the argument to +@code{@@sc} is printed in all uppercase. In HTML, the argument is +uppercased and the output marked with the @code{<small>} tag to reduce +the font size, since HTML cannot easily represent true small caps. + +Overall, we recommend using standard upper- and lowercase letters +wherever possible. + + +@node Fonts +@subsection Fonts for Printing +@cindex Fonts for printing + +@findex fonttextsize +@cindex Font size, reducing +@cindex Reducing font size +@cindex Smaller fonts +Texinfo provides one command to change the size of the main body font +in the @TeX{} output for a document: @code{@@fonttextsize}. It has no +effect in other output. It takes a single argument on the remainder +of the line, which must be either @samp{10} or @samp{11}. For +example: + +@example +@@fonttextsize 10 +@end example + +@cindex Printing cost, reducing +The effect is to reduce the body font to a 10@dmn{pt} size (the +default is 11@dmn{pt}). Fonts for other elements, such as sections +and chapters, are reduced accordingly. This should only be used in +conjunction with @code{@@smallbook} (@pxref{@code{@@smallbook}}) or +similar, since 10@dmn{pt} fonts on standard paper (8.5x11 or A4) are +too small. One reason to use this command is to save pages, and hence +printing cost, for physical books. + +Texinfo does not at present have commands to switch the font family +to use, or more general size-changing commands. + +Texinfo also provides a number of font commands that specify font +changes in the printed manual and (where possible) in the HTML output. +They have no effect in Info. All the commands apply to a following +argument surrounded by braces. + +@table @code +@item @@b +@findex b @r{(bold font)} +@cindex Bold font +selects @b{bold} face; + +@item @@i +@findex i @r{(italic font)} +@cindex Italic font +selects an @i{italic} font; + +@item @@r +@findex r @r{(roman font)} +@cindex Roman font +@cindex Default font +selects a @r{roman} font, which is the usual font in which text is +printed. It may or may not be seriffed. + +@item @@sansserif +@findex sansserif @r{(sans serif font)} +@cindex Sans serif font +selects a @sansserif{sans serif} font; + +@item @@slanted +@findex slanted @r{(slanted font)} +@cindex Slanted font +@cindex Oblique font +selects a @slanted{slanted} font; + +@item @@t +@findex t @r{(typewriter font)} +@cindex Monospace font +@cindex Fixed-width font +@cindex Typewriter font +selects the @t{fixed-width}, typewriter-style font used by @code{@@code}; + +@end table + +(The commands with longer names were invented much later than the +others, at which time it did not seem desirable to use very short +names for such infrequently needed features.) + +@cindex @code{<lineannotation>} Docbook tag +The @code{@@r} command can be useful in example-like environments, to +write comments in the standard roman font instead of the fixed-width +font. This looks better in printed output, and produces a +@code{<lineannotation>} tag in Docbook output. + +For example, + +@example +@group +@@lisp +(+ 2 2) ; @@r@{Add two plus two.@} +@@end lisp +@end group +@end example + +@noindent +produces + +@lisp +(+ 2 2) ; @r{Add two plus two.} +@end lisp + +The @code{@@t} command can occasionally be useful to produce output in +a typewriter font where that is supported (e.g., HTML and PDF), but no +distinction is needed in Info or plain text: @code{@@t@{foo@}} +produces @t{foo}, cf. @code{@@code@{foo@}} producing @code{foo}. + +In general, the other font commands are unlikely to be useful; they +exist primarily to make it possible to document the functionality of +specific font effects, such as in @TeX{} and related packages. + + +@node Quotations and Examples +@chapter Quotations and Examples + +Quotations and examples are blocks of text consisting of one or more +whole paragraphs that are set off from the bulk of the text and +treated differently. They are usually indented in the output. + +@findex end +In Texinfo, you always begin a quotation or example by writing an +@@-command at the beginning of a line by itself, and end it by writing +an @code{@@end} command that is also at the beginning of a line by +itself. For instance, you begin an example by writing +@code{@@example} by itself at the beginning of a line and end the +example by writing @code{@@end example} on a line by itself, at the +beginning of that line, and with only one space between the +@code{@@end} and the @code{example}. + +@menu +* Block Enclosing Commands:: Different constructs for different purposes. +* @code{@@quotation}:: Writing a quotation. +* @code{@@indentedblock}:: Block of text indented on left. +* @code{@@example}:: Writing an example in a fixed-width font. +* @code{@@verbatim}:: Writing a verbatim example. +* @code{@@lisp}:: Illustrating Lisp code. +* @code{@@display}:: Writing an example in the current font. +* @code{@@format}:: Writing an example without narrowed margins. +* @code{@@exdent}:: Undo indentation on a line. +* @code{@@flushleft @@flushright}:: Pushing text flush left or flush right. +* @code{@@raggedright}:: Avoiding justification on the right. +* @code{@@noindent}:: Preventing paragraph indentation. +* @code{@@indent}:: Forcing paragraph indentation. +* @code{@@cartouche}:: Drawing rounded rectangles around text. +* @code{@@small@dots{}}:: Examples in a smaller font. +@end menu + + +@node Block Enclosing Commands +@section Block Enclosing Commands + +Here is a summary of commands that enclose blocks of text, also known +as @dfn{environments}. They're explained further in the following +sections. + +@table @code +@item @@quotation +Indicate text that is quoted. The text is filled, indented (from both +margins), and printed in a roman font by default. + +@item @@indentedblock +Like @code{@@quotation}, but the text is indented only on the left. + +@item @@example +Illustrate code, commands, and the like. The text is printed +in a fixed-width font, and indented but not filled. + +@item @@lisp +Like @code{@@example}, but specifically for illustrating Lisp code. The +text is printed in a fixed-width font, and indented but not filled. + +@item @@verbatim +Mark a piece of text that is to be printed verbatim; no character +substitutions are made and all commands are ignored, until the next +@code{@@end verbatim}. The text is printed in a fixed-width font, +and not indented or filled. Extra spaces and blank lines are +significant, and tabs are expanded. + +@item @@display +Display illustrative text. The text is indented but not filled, and +no font is selected (so, by default, the font is roman). + +@item @@format +Like @code{@@display} (the text is not filled and no font is +selected), but the text is not indented. + +@item @@smallquotation +@itemx @@smallindentedblock +@itemx @@smallexample +@itemx @@smalllisp +@itemx @@smalldisplay +@itemx @@smallformat +These @code{@@small...} commands are just like their non-small +counterparts, except that they output text in a smaller font size, +where possible. + +@item @@flushleft +@itemx @@flushright +Text is not filled, but is set flush with the left or right margin, +respectively. + +@item @@raggedright +Text is filled, but only justified on the left, leaving the right +margin ragged. + +@item @@cartouche +Highlight text, often an example or quotation, by drawing a box with +rounded corners around it. +@end table + +The @code{@@exdent} command is used within the above constructs to +undo the indentation of a line. + +The @code{@@noindent} command may be used after one of the above +constructs (or at the beginning of any paragraph) to prevent the +following text from being indented as a new paragraph. + + +@node @code{@@quotation} +@section @code{@@quotation}: Block Quotations +@anchor{quotation}@c old name + +@cindex Quotations +@findex quotation + +The text of a quotation is processed like normal text (regular font, +text is filled) except that: + +@itemize @bullet +@item +both the left and right margins are closer to the center of the page, +so the whole of the quotation is indented; + +@item +the first lines of paragraphs are indented no more than other lines; and + +@item +an @code{@@author} command may be given to specify the author of the +quotation. +@end itemize + +@quotation +This is an example of text written between a @code{@@quotation} +command and an @code{@@end quotation} command. A @code{@@quotation} +command is most often used to indicate text that is excerpted from +another (real or hypothetical) printed work. +@end quotation + +Write a @code{@@quotation} command as text on a line by itself. This +line will disappear from the output. Mark the end of the quotation +with a line beginning with and containing only @code{@@end quotation}. +The @code{@@end quotation} line will likewise disappear from the +output. + +@code{@@quotation} takes one optional argument, given on the remainder +of the line. This text, if present, is included at the beginning of +the quotation in bold or otherwise emphasized, and followed with a +@samp{:}. For example: + +@example +@@quotation Note +This is +a foo. +@@end quotation +@end example + +@noindent +produces + +@quotation Note +This is +a foo. +@end quotation + +If the @code{@@quotation} argument is one of these English words +(case-insensitive): + +@example +Caution Important Note Tip Warning +@end example + +@cindex @code{<caution>} Docbook tag +@cindex @code{<important>} Docbook tag +@cindex @code{<note>} Docbook tag +@cindex @code{<tip>} Docbook tag +@cindex @code{<warning>} Docbook tag +@cindex @code{<blockquote>} HTML tag +@noindent then the Docbook output uses corresponding special tags +(@code{<note>}, etc.)@: instead of the default @code{<blockquote>}. +HTML output always uses @code{<blockquote>}. + +If the author of the quotation is specified in the @code{@@quotation} +block with the @code{@@author} command, a line with the author name is +displayed after the quotation: + +@example +@@quotation +People sometimes ask me if it is a sin in the Church of Emacs to use +vi. Using a free version of vi is not a sin; it is a penance. So happy +hacking. + +@@author Richard Stallman +@@end quotation +@end example + +@noindent +produces + +@quotation +People sometimes ask me if it is a sin in the Church of Emacs to use +vi. Using a free version of vi is not a sin; it is a penance. So happy +hacking. + +@author Richard Stallman +@end quotation + +@findex smallquotation +Texinfo also provides a command @code{@@smallquotation}, which is just +like @code{@@quotation} but uses a smaller font size where possible. +@xref{@code{@@small@dots{}}}. + + +@node @code{@@indentedblock} +@section @code{@@indentedblock}: Indented text blocks +@cindex Indented text block +@findex indentedblock + +The @code{@@indentedblock} environment is similar to +@code{@@quotation}, except that text is only indented on the left (and +there is no optional argument for an author). Thus, the text font +remains unchanged, and text is gathered and filled as usual, but the +left margin is increased. For example: + +@indentedblock +This is an example of text written between an @code{@@indentedblock} +command and an @code{@@end indentedblock} command. The +@code{@@indentedblock} environment can contain any text or other +commands desired. +@end indentedblock + +This is written in the Texinfo source as: + +@example +@@indentedblock +This is an example ... +@@end indentedblock +@end example + +@findex smallindentedblock +Texinfo also provides a command @code{@@smallindentedblock}, which is +just like @code{@@indentedblock} but uses a smaller font size where +possible. @xref{@code{@@small@dots{}}}. + + +@node @code{@@example} +@section @code{@@example}: Example Text + +@anchor{example}@c old name +@findex example +@cindex Examples, formatting them +@cindex Formatting examples + +The @code{@@example} environment is used to indicate an example that +is not part of the running text, such as computer input or output. +Write an @code{@@example} command at the beginning of a line by +itself. Mark the end of the example with an @code{@@end example} +command, also written at the beginning of a line by itself. + +An @code{@@example} environment has the following characteristics: + +@itemize +@item Each line in the input file is a line in the output; that is, +the source text is not filled as it normally is. +@item Extra spaces and blank lines are significant. +@item The output is indented. +@item The output uses a fixed-width font. +@item Texinfo commands @emph{are} expanded; if you want the output to +be the input verbatim, use the @code{@@verbatim} environment instead +(@pxref{@code{@@verbatim}}). +@end itemize + +For example, + +@example +@@example +cp foo @@var@{dest1@}; \ + cp foo @@var@{dest2@} +@@end example +@end example + +@noindent +produces + +@example +cp foo @var{dest1}; \ + cp foo @var{dest2} +@end example + +The lines containing @code{@@example} and @code{@@end example} will +disappear from the output. To make the output look good, you should +put a blank line before the @code{@@example} and another blank line +after the @code{@@end example}. Blank lines inside the beginning +@code{@@example} and the ending @code{@@end example}, on the other +hand, do appear in the output. + +@quotation Caution +Do not use tabs in the lines of an example! (Or anywhere else in +Texinfo, except in verbatim environments.) @TeX{} treats tabs as +single spaces, and that is not what they look like. In Emacs, you can +use @kbd{M-x untabify} to convert tabs in a region to multiple spaces. +@end quotation + +Examples are often, logically speaking, ``in the middle'' of a +paragraph, and the text that continues afterwards should not be +indented, as in the example above. The @code{@@noindent} command +prevents a piece of text from being indented as if it were a new +paragraph (@pxref{@code{@@noindent}}). + +If you want to embed code fragments within sentences, instead of +displaying them, use the @code{@@code} command or its relatives +(@pxref{@code{@@code}}). + +If you wish to write a ``comment'' on a line of an example in the +normal roman font, you can use the @code{@@r} command (@pxref{Fonts}). + + +@node @code{@@verbatim} +@section @code{@@verbatim}: Literal Text + +@anchor{verbatim}@c old name +@findex verbatim +@cindex Verbatim environment + +Use the @code{@@verbatim} environment for printing of text that may +contain special characters or commands that should not be interpreted, +such as computer input or output (@code{@@example} interprets its text +as regular Texinfo commands). This is especially useful for including automatically +generated files in a Texinfo manual. + +In general, the output will be just the same as the input. No +character substitutions are made, e.g., all spaces and blank lines are +significant, including tabs. In the printed manual, the text is +typeset in a fixed-width font, and not indented or filled. + +Write a @code{@@verbatim} command at the beginning of a line by +itself. This line will disappear from the output. Mark the end of +the verbatim block with an @code{@@end verbatim} command, also written +at the beginning of a line by itself. The @code{@@end verbatim} will +also disappear from the output. + +For example: +@c oops, got to trick this a bit: can't use @end verbatim inside @verbatim + +@example +@exdent @t{@@verbatim} +@exdent @t{@{} +@exdent @key{TAB}@t{@@command with strange characters: @@'e} +@exdent @t{expand@key{TAB}me} +@exdent @t{@}} +@exdent @t{@@end verbatim} +@end example + +@noindent +This produces: + +@verbatim +{ + @command with strange characters: @'e +expand me +} +@end verbatim + +Since the lines containing @code{@@verbatim} and @code{@@end verbatim} +produce no output, typically you should put a blank line before the +@code{@@verbatim} and another blank line after the @code{@@end +verbatim}. Blank lines between the beginning @code{@@verbatim} and +the ending @code{@@end verbatim} will appear in the output. + +@cindex Verbatim, small +@cindex Small verbatim +You can get a ``small'' verbatim by enclosing the @code{@@verbatim} in +an @code{@@smallformat} environment, as shown here: + +@c more cheating ... +@smallexample +@exdent @t{@@smallformat} +@exdent @t{@@verbatim} +@exdent @t{... still verbatim, but in a smaller font ...} +@exdent @t{@@end verbatim} +@exdent @t{@@end smallformat} +@end smallexample + +Finally, a word of warning: it is not reliable to use +@code{@@verbatim} inside other Texinfo constructs. + +See also @ref{@code{@@verbatiminclude}}. + + +@node @code{@@lisp} +@section @code{@@lisp}: Marking a Lisp Example + +@anchor{lisp}@c old name +@findex lisp +@cindex Lisp example + +The @code{@@lisp} command is used for Lisp code. It is synonymous +with the @code{@@example} command. + +@lisp +This is an example of text written between an +@code{@@lisp} command and an @code{@@end lisp} command. +@end lisp + +Use @code{@@lisp} instead of @code{@@example} to preserve information +regarding the nature of the example. This is useful, for example, if +you write a function that evaluates only and all the Lisp code in a +Texinfo file. Then you can use the Texinfo file as a Lisp +library. Mark the end of @code{@@lisp} with @code{@@end lisp} on a line +by itself. + + +@node @code{@@display} +@section @code{@@display}: Examples Using the Text Font + +@anchor{display}@c old name +@findex display +@cindex Display formatting + +The @code{@@display} command begins another kind of environment, where +the font is left unchanged, not switched to typewriter as with +@code{@@example}. Each line of input still produces a line of output, +and the output is still indented. + +@display +This is an example of text written between a @code{@@display} command +and an @code{@@end display} command. The @code{@@display} command +indents the text, but does not fill it. +@end display + +@findex smalldisplay +Texinfo also provides the environment @code{@@smalldisplay}, which is +like @code{@@display} but uses a smaller font size. +@xref{@code{@@small@dots{}}}. + + +@node @code{@@format} +@section @code{@@format}: Examples Using the Full Line Width + +@anchor{format}@c old name +@findex format + +The @code{@@format} command is similar to @code{@@display}, except it +leaves the text unindented. Like @code{@@display}, it does not select +the fixed-width font. + +@format +This is an example of text written between a @code{@@format} command +and an @code{@@end format} command. As you can see +from this example, +the @code{@@format} command does not fill the text. +@end format + +@findex smallformat +Texinfo also provides the environment @code{@@smallformat}, which is +like @code{@@format} but uses a smaller font size. +@xref{@code{@@small@dots{}}}. + + +@node @code{@@exdent} +@section @code{@@exdent}: Undoing a Line's Indentation + +@anchor{exdent}@c old name +@findex exdent +@cindex Indentation undoing + +The @code{@@exdent} command removes any indentation a line might have. +The command is written at the beginning of a line and applies only to +the text that follows the command that is on the same line. Do not use +braces around the text. In a printed manual, the text on an +@code{@@exdent} line is printed in the roman font. + +@code{@@exdent} is usually used within examples. Thus, + +@example +@group +@@example +This line follows an @@@@example command. +@@exdent This line is exdented. +This line follows the exdented line. +The @@@@end example comes on the next line. +@@end example +@end group +@end example + +@noindent +produces + +@example +@group +This line follows an @@example command. +@exdent This line is exdented. +This line follows the exdented line. +The @@end example comes on the next line. +@end group +@end example + +In practice, the @code{@@exdent} command is rarely used. Usually, you +un-indent text by ending the example and returning the page to its +normal width. + +@code{@@exdent} has no effect in HTML output. + + +@node @code{@@flushleft @@flushright} +@section @code{@@flushleft} and @code{@@flushright} + +@anchor{flushleft & flushright}@c old name +@findex flushleft +@findex flushright +@cindex Ragged right, without filling +@cindex Ragged left, without filling + +The @code{@@flushleft} and @code{@@flushright} commands line up the +ends of lines on the left and right margins of a page, +but do not fill the text. The commands are written on lines of their +own, without braces. The @code{@@flushleft} and @code{@@flushright} +commands are ended by @code{@@end flushleft} and @code{@@end +flushright} commands on lines of their own. + +@need 1500 +For example, + +@example +@group +@@flushleft +This text is +written flushleft. +@@end flushleft +@end group +@end example + +@noindent +produces + +@quotation +@flushleft +This text is +written flushleft. +@end flushleft +@end quotation + + +@code{@@flushright} produces the type of indentation often used in the +return address of letters. For example, + +@example +@group +@@flushright +Here is an example of text written +flushright. The @@code@{@@flushright@} command +right justifies every line but leaves the +left end ragged. +@@end flushright +@end group +@end example + +@noindent +produces + +@flushright +Here is an example of text written +flushright. The @code{@@flushright} command +right justifies every line but leaves the +left end ragged. +@end flushright + + +@node @code{@@raggedright} +@section @code{@@raggedright}: Ragged Right Text + +@anchor{raggedright}@c old name +@findex raggedright +@cindex Ragged right, with filling + +The @code{@@raggedright} fills text as usual, but the text is only +justified on the left; the right margin is ragged. The command is +written on a line of its own, without braces. The +@code{@@raggedright} command is ended by @code{@@end raggedright} on a +line of its own. This command has no effect in Info and HTML output, +where text is always set ragged right. + +The @code{@@raggedright} command can be useful with paragraphs +containing lists of commands with long names, when it is known in +advance that justifying the text on both margins will make the +paragraph look bad. + +An example (from elsewhere in this manual): + +@example +@group +@@raggedright +Commands for double and single angle quotation marks: +@@code@{@@@@guillemetleft@@@{@@@}@}, @@code@{@@@@guillemetright@@@{@@@}@}, +@@code@{@@@@guillemotleft@@@{@@@}@}, @@code@{@@@@guillemotright@@@{@@@}@}, +@@code@{@@@@guilsinglleft@@@{@@@}@}, @@code@{@@@@guilsinglright@@@{@@@}@}. +@@end raggedright +@end group +@end example + +@noindent +produces + +@raggedright +Commands for double and single angle quotation marks: +@code{@@guillemetleft@{@}}, @code{@@guillemetright@{@}}, +@code{@@guillemotleft@{@}}, @code{@@guillemotright@{@}}, +@code{@@guilsinglleft@{@}}, @code{@@guilsinglright@{@}}. +@end raggedright + + +@node @code{@@noindent} +@section @code{@@noindent}: Omitting Indentation + +@anchor{noindent}@c old name +@findex noindent +@cindex Omitting indentation +@cindex Suppressing indentation +@cindex Indentation, omitting + +An example or other inclusion can break a paragraph into segments. +Ordinarily, the formatters indent text that follows an example as a new +paragraph. You can prevent this on a case-by-case basis by writing +@code{@@noindent} at the beginning of a line, preceding the continuation +text. You can also disable indentation for all paragraphs globally with +@code{@@paragraphindent} (@pxref{@code{@@paragraphindent}}). + +Here is an example showing how to eliminate the normal indentation of +the text after an @code{@@example}, a common situation: + +@example +@group +@@example +This is an example +@@end example + +@@noindent +This line is not indented. As you can see, the +beginning of the line is fully flush left with the +line that follows after it. +@end group +@end example + +@noindent produces: + +@display +@example +This is an example +@end example + +@noindent +This line is not indented. As you can see, the +beginning of the line is fully flush left with the +line that follows after it. +@end display + +The standard usage of @code{@@noindent} is just as above: at the +beginning of what would otherwise be a paragraph, to eliminate the +indentation that normally happens there. It can either be followed by +text or be on a line by itself. There is no reason to use it +in other contexts, such as in the middle of a paragraph or inside an +environment (@pxref{Quotations and Examples}). + +You can control the number of blank lines in the Info file output by +adjusting the input as desired: a line containing just +@code{@@noindent} does not generate a blank line, and neither does an +@code{@@end} line for an environment. + +Do not put braces after a @code{@@noindent} command; they are not +used, since @code{@@noindent} is a command used outside of paragraphs +(@pxref{Command Syntax}). + + +@node @code{@@indent} +@section @code{@@indent}: Forcing Indentation + +@anchor{indent}@c old name +@findex indent +@cindex Forcing indentation +@cindex Inserting indentation +@cindex Indentation, forcing + +@indent +To complement the @code{@@noindent} command (see the previous +section), Texinfo provides the @code{@@indent} command to force a +paragraph to be indented. For instance, this paragraph (the first in +this section) is indented using an @code{@@indent} command. + +And indeed, the first paragraph of a section is the most likely place +to use @code{@@indent}, to override the normal behavior of no +indentation there (@pxref{@code{@@paragraphindent}}). It can either be +followed by text or be on a line by itself. + +As a special case, when @code{@@indent} is used in an environment +where text is not filled, it produces a paragraph indentation space in +the @TeX{} output. (These environments are where a line of input +produces a line of output, such as @code{@@example} and +@code{@@display}; for a summary of all environments, @pxref{Block +Enclosing Commands}.) + +Do not put braces after an @code{@@indent} command; they are not used, +since @code{@@indent} is a command used outside of paragraphs +(@pxref{Command Syntax}). + + +@node @code{@@cartouche} +@section @code{@@cartouche}: Rounded Rectangles + +@anchor{cartouche}@c old name +@findex cartouche +@cindex Box with rounded corners +@cindex Rounded rectangles, around text + +In a printed manual, the @code{@@cartouche} command draws a box with +rounded corners around its contents. In HTML, a normal rectangle is +drawn. @code{@@cartouche} has no effect in Info output. + +You can use this command to further highlight an example or quotation. +For instance, you could write a manual in which one type of example is +surrounded by a cartouche for emphasis. + +For example, + +@example +@@cartouche +@@example +% pwd +/usr/local/share/emacs +@@end example +@@end cartouche +@end example + +@noindent +surrounds the two-line example with a box with rounded corners, in the +printed manual. + +The output from the example looks like this (if you're reading this in +Info, you'll see the @code{@@cartouche} had no effect): + +@cartouche +@example +% pwd +/usr/local/share/emacs +@end example +@end cartouche + +@code{@@cartouche} also implies @code{@@group} (@pxref{@code{@@group}}). + +@node @code{@@small@dots{}} +@section @code{@@small@dots{}} Block Commands + +@anchor{small}@c old name +@findex smallexample +@findex smallformat +@findex smalllisp +@findex smallquotation +@cindex Small examples +@cindex Examples in smaller fonts +@cindex Quotations in smaller fonts +@cindex Lisp examples in smaller fonts + +In addition to the regular @code{@@example} and similar commands, +Texinfo has ``small'' example-style commands. These are +@code{@@smallquotation}, @code{@@smallindentedblock}, +@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, +and @code{@@smalllisp}. + +In Info and HTML output, the @code{@@small@dots{}} commands are +equivalent to their non-small companion commands. + +In @TeX{}, however, the @code{@@small@dots{}} commands typeset text in +a smaller font than the non-small example commands. Thus, for +instance, code examples can contain longer lines and still fit on a +page without needing to be rewritten. + +A smaller font size is also retained in the Texinfo@tie{}XML transliteration. + +Mark the end of a @code{@@small@dots{}} block with a corresponding +@code{@@end small@dots{}}. For example, pair @code{@@smallexample} with +@code{@@end smallexample}. + +Here is an example of the font used by the @code{@@smallexample} +command (in Info, the output will be the same as usual): + +@smallexample +@dots{} to make sure that you have the freedom to +distribute copies of free software (and charge for +this service if you wish), that you receive source +code or can get it if you want it, that you can +change the software or use pieces of it in new free +programs; and that you know you can do these things. +@end smallexample + +The @code{@@small@dots{}} commands use the same font style as their +normal counterparts: @code{@@smallexample} and @code{@@smalllisp} use +a fixed-width font, and everything else uses the regular font. +They also have the same behavior in other respects---whether filling +is done and whether margins are narrowed. + +As a general rule, a printed document looks better if you use only one +of (for instance) @code{@@example} or @code{@@smallexample} +consistently within a chapter. + + + + +@node Lists and Tables +@chapter Lists and Tables +@cindex Making lists and tables +@cindex Lists and tables, making +@cindex Tables and lists, making + +Texinfo has several ways of making lists and tables. Lists can be +bulleted or numbered; two-column tables can highlight the items in +the first column; multi-column tables are also supported. + +@menu +* Introducing Lists:: Texinfo formats lists for you. +* @code{@@itemize}:: How to construct a simple list. +* @code{@@enumerate}:: How to construct a numbered list. +* Two-column Tables:: How to construct a two-column table. +* Multi-column Tables:: How to construct generalized tables. +@end menu + +@node Introducing Lists +@section Introducing Lists + +Texinfo automatically indents the text in lists or tables, and numbers +an enumerated list. This last feature is useful if you modify the +list, since you do not need to renumber it yourself. + +Numbered lists and tables begin with the appropriate @@-command at the +beginning of a line, and end with the corresponding @code{@@end} +command on a line by itself. The table and itemized-list commands +also require that you write formatting information on the same line as +the beginning @@-command. + +Begin an enumerated list, for example, with an @code{@@enumerate} +command and end the list with an @code{@@end enumerate} command. +Begin an itemized list with an @code{@@itemize} command, followed on +the same line by a formatting command such as @code{@@bullet}, and end +the list with an @code{@@end itemize} command. +@findex end + +Precede each element of a list with an @code{@@item} or @code{@@itemx} +command. + +@sp 1 +@noindent +Here is an itemized list of the different kinds of table and lists: + +@itemize @bullet +@item +Itemized lists with and without bullets. + +@item +Enumerated lists, using numbers or letters. + +@item +Two-column tables with highlighting. +@end itemize + +@sp 1 +@noindent +Here is an enumerated list with the same items: + +@enumerate +@item +Itemized lists with and without bullets. + +@item +Enumerated lists, using numbers or letters. + +@item +Two-column tables with highlighting. +@end enumerate + +@sp 1 +@noindent +And here is a two-column table with the same items and their +@w{@@-commands}: + +@table @code +@item @@itemize +Itemized lists with and without bullets. + +@item @@enumerate +Enumerated lists, using numbers or letters. + +@item @@table +@itemx @@ftable +@itemx @@vtable +Two-column tables, optionally with indexing. +@end table + + +@node @code{@@itemize} +@section @code{@@itemize}: Making an Itemized List + +@anchor{itemize}@c old name +@findex itemize +@cindex Itemization + +The @code{@@itemize} command produces a sequence of ``items'', each +starting with a bullet or other mark inside the left margin, and +generally indented. + +@cindex @code{@@w}, for blank items +Begin an itemized list by writing @code{@@itemize} at the beginning of +a line. Follow the command, on the same line, with a character or a +Texinfo command that generates a mark. Usually, you will use +@code{@@bullet} after @code{@@itemize}, but you can use +@code{@@minus}, or any command or character that results in a single +character in the Info file. (When you write the mark command such as +@code{@@bullet} after an @code{@@itemize} command, you may omit the +@samp{@{@}}.) If you don't specify a mark command, the default is +@code{@@bullet}. If you don't want any mark at all, but still want +logical items, use @code{@@w@{@}} (in this case the braces are +required). + +@findex item +After the @code{@@itemize}, write your items, each starting with +@code{@@item}. Text can follow on the same line as the @code{@@item}. +The text of an item can continue for more than one paragraph. + +There should be at least one @code{@@item} inside the @code{@@itemize} +environment. If none are present, @code{makeinfo} gives a warning. +If you just want indented text and not a list of items, use +@code{@@indentedblock}; @pxref{@code{@@indentedblock}}. + +Index entries and comments that are given before an @code{@@item} +including the first, are automatically moved (internally) to after the +@code{@@item}, so the output is as expected. Historically this has +been a common practice. + +Usually, you should put a blank line between items. This puts a blank +line in the Info file. (@TeX{} inserts the proper vertical space in +any case.) Except when the entries are very brief, these blank lines +make the list look better. + +Here is an example of the use of @code{@@itemize}, followed by the +output it produces. @code{@@bullet} produces an @samp{*} in Info and +a round dot in other output formats. + +@example +@group +@@itemize @@bullet +@@item +Some text for foo. + +@@item +Some text +for bar. +@@end itemize +@end group +@end example + +@noindent +This produces: + +@quotation +@itemize @bullet +@item +Some text for foo. + +@item +Some text +for bar. +@end itemize +@end quotation + +Itemized lists may be embedded within other itemized lists. Here is a +list marked with dashes embedded in a list marked with bullets: + +@example +@group +@@itemize @@bullet +@@item +First item. + +@@itemize @@minus +@@item +Inner item. + +@@item +Second inner item. +@@end itemize + +@@item +Second outer item. +@@end itemize +@end group +@end example + +@noindent +This produces: + +@quotation +@itemize @bullet +@item +First item. + +@itemize @minus +@item +Inner item. + +@item +Second inner item. +@end itemize + +@item +Second outer item. +@end itemize +@end quotation + + +@node @code{@@enumerate} +@section @code{@@enumerate}: Making a Numbered or Lettered List + +@anchor{enumerate}@c old name +@findex enumerate +@cindex Enumeration + +@code{@@enumerate} is like @code{@@itemize} (@pxref{@code{@@itemize}}), +except that the labels on the items are successive integers or letters +instead of bullets. + +Write the @code{@@enumerate} command at the beginning of a line. The +command does not require an argument, but accepts either a number or a +letter as an option. Without an argument, @code{@@enumerate} starts the +list with the number @samp{1}. With a numeric argument, such as +@samp{3}, the command starts the list with that number. With an upper- +or lowercase letter, such as @samp{a} or @samp{A}, the command starts +the list with that letter. + +Write the text of the enumerated list in the same way as an itemized +list: write a line starting with @code{@@item} at the beginning of +each item in the enumeration. It is ok to have text following the +@code{@@item}, and the text for an item can continue for several +paragraphs. + +You should put a blank line between entries in the list. +This generally makes it easier to read the Info file. + +@need 1500 +Here is an example of @code{@@enumerate} without an argument: + +@example +@group +@@enumerate +@@item +Underlying causes. + +@@item +Proximate causes. +@@end enumerate +@end group +@end example + +@noindent +This produces: + +@enumerate +@item +Underlying causes. + +@item +Proximate causes. +@end enumerate +@sp 1 +Here is an example with an argument of @kbd{3}: +@sp 1 +@example +@group +@@enumerate 3 +@@item +Predisposing causes. + +@@item +Precipitating causes. + +@@item +Perpetuating causes. +@@end enumerate +@end group +@end example + +@noindent +This produces: + +@enumerate 3 +@item +Predisposing causes. + +@item +Precipitating causes. + +@item +Perpetuating causes. +@end enumerate +@sp 1 +Here is a brief summary of the alternatives. The summary is constructed +using @code{@@enumerate} with an argument of @kbd{a}. +@sp 1 +@enumerate a +@item +@code{@@enumerate} + +Without an argument, produce a numbered list, with the first item +numbered@tie{}1. + +@item +@code{@@enumerate @var{unsigned-integer}} + +With an (unsigned) numeric argument, start a numbered list with that +number. You can use this to continue a list that you interrupted with +other text. + +@item +@code{@@enumerate @var{upper-case-letter}} + +With an uppercase letter as argument, start a list +in which each item is marked +by a letter, beginning with that uppercase letter. + +@item +@code{@@enumerate @var{lower-case-letter}} + +With a lowercase letter as argument, start a list +in which each item is marked by +a letter, beginning with that lowercase letter. +@end enumerate + +You can also nest enumerated lists, as in an outline. + + +@node Two-column Tables +@section Making a Two-column Table + +@cindex Tables, making two-column +@findex table + +@code{@@table} is similar to @code{@@itemize} +(@pxref{@code{@@itemize}}), but allows you to specify a name or +heading line for each item. The @code{@@table} command is used to +produce two-column tables, and is especially useful for glossaries, +explanatory exhibits, and command-line option summaries. + +@menu +* @code{@@table}:: How to construct a two-column table. +* @code{@@ftable @@vtable}:: Automatic indexing for two-column tables. +* @code{@@itemx}:: How to put more entries in the first column. +@end menu + +@node @code{@@table} +@subsection Using the @code{@@table} Command + +@anchor{table}@c old name + +@cindex Definition lists, typesetting +Use the @code{@@table} command to produce a two-column table. This +command is typically used when you have a list of items and a brief text +with each one, such as a list of definitions. + +Write the @code{@@table} command at the beginning of a line, after a +blank line, and follow it on the same line with an argument that is an +`indicating' command, such as @code{@@code}, @code{@@samp}, +@code{@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}). +This command will be applied to the text in the first column. For +example, @code{@@table @@code} will cause the text in the first column +to be output as if it had been the argument to a @code{@@code} command. + +@anchor{@code{@@asis}}@c command name with @, for consistency +@findex asis +You may use the @code{@@asis} command as an argument to +@code{@@table}. @code{@@asis} is a command that does nothing: if you +use this command after @code{@@table}, the first column entries are +output without added highlighting (``as is''). + +The @code{@@table} command works with other commands besides those +explicitly mentioned here. However, you can only use predefined +Texinfo commands that take an argument in braces. You cannot +reliably use a new command defined with @code{@@macro}, although an +@code{@@alias} (for a suitable predefined command) is acceptable. +@xref{Defining New Texinfo Commands}. + +@findex item +Begin each table entry with an @code{@@item} command at the beginning +of a line. Write the text for the first column on the same line as the +@code{@@item} command. Write the text for the second column on the line +following the @code{@@item} line and on subsequent lines. You may +write as many lines of supporting text as you wish, even several +paragraphs. But only the text on the same line as the @code{@@item} +will be placed in the first column (including any footnotes). +You do not need to type anything for an empty second column. + +Normally, you should put a blank line before an @code{@@item} line +(except the first one). This puts a blank line in the Info file. +Except when the entries are very brief, a blank line looks better. +End the table with a line consisting of @code{@@end table}, followed +by a blank line. @TeX{} will always start a new paragraph after the +table, so the blank line is needed for the Info output to be analogous. + +@need 1500 +For example, the following table highlights the text in the first +column with the @code{@@samp} command: + +@example +@group +@@table @@samp +@@item foo +This is the text for +@@samp@{foo@}. + +@@item bar +Text for @@samp@{bar@}. +@@end table +@end group +@end example + +@noindent +This produces: + +@table @samp +@item foo +This is the text for +@samp{foo}. +@item bar +Text for @samp{bar}. +@end table + +If you want to list two or more named items with a single block of +text, use the @code{@@itemx} command. (@xref{@code{@@itemx}}.) + +The @code{@@table} command (@pxref{@code{@@table}}) is not supported +inside @code{@@display}. Since @code{@@display} is line-oriented, it +doesn't make sense to use them together. If you want to indent a +table, try @code{@@quotation} (@pxref{@code{@@quotation}}) or +@code{@@indentedblock} (@pxref{@code{@@indentedblock}}). + +@node @code{@@ftable @@vtable} +@subsection @code{@@ftable} and @code{@@vtable} + +@anchor{ftable vtable}@c old name +@findex ftable +@findex vtable +@cindex Tables with indexing +@cindex Indexing table entries automatically + +The @code{@@ftable} and @code{@@vtable} commands are the same as the +@code{@@table} command except that @code{@@ftable} automatically enters +each of the items in the first column of the table into the index of +functions and @code{@@vtable} automatically enters each of the items in +the first column of the table into the index of variables. This +simplifies the task of creating indices. Only the items on the same +line as the @code{@@item} or @code{@@itemx} commands are indexed, and +they are indexed in exactly the form that they appear on that line. +@xref{Indices}, for more information about indices. + +Begin a two-column table using @code{@@ftable} or @code{@@vtable} by +writing the @@-command at the beginning of a line, followed on the same +line by an argument that is a Texinfo command such as @code{@@code}, +exactly as you would for a @code{@@table} command; and end the table +with an @code{@@end ftable} or @code{@@end vtable} command on a line by +itself. + +See the example for @code{@@table} in the previous section. + + +@node @code{@@itemx} +@subsection @code{@@itemx}: Second and Subsequent Items + +@anchor{itemx}@c old name +@cindex Two named items for @code{@@table} +@findex itemx + +Use the @code{@@itemx} command inside a table when you have two or more +first column entries for the same item, each of which should appear on a +line of its own. + +Use @code{@@item} for the first entry, and @code{@@itemx} for all +subsequent entries; @code{@@itemx} must always follow an @code{@@item} +command, with no blank line intervening. + +The @code{@@itemx} command works exactly like @code{@@item} except +that it does not generate extra vertical space above the first column +text. If you have multiple consecutive @code{@@itemx} commands, do +not insert any blank lines between them. + +For example, + +@example +@group +@@table @@code +@@item upcase +@@itemx downcase +These two functions accept a character or a string as +argument, and return the corresponding uppercase (lowercase) +character or string. +@@end table +@end group +@end example + +@noindent +This produces: + +@table @code +@item upcase +@itemx downcase +These two functions accept a character or a string as +argument, and return the corresponding uppercase (lowercase) +character or string. +@end table + +@noindent +(Note also that this example illustrates multi-line supporting text in +a two-column table.) + + +@node Multi-column Tables +@section @code{@@multitable}: Multi-column Tables + +@findex multitable +@cindex Tables, making multi-column + +@code{@@multitable} allows you to construct tables with any number of +columns, with each column having any width you like. + +You define the column widths on the @code{@@multitable} line itself, and +write each row of the actual table following an @code{@@item} command, +with columns separated by a @code{@@tab} command. Finally, @code{@@end +multitable} completes the table. Details in the sections below. + +@menu +* Multitable Column Widths:: Defining multitable column widths. +* Multitable Rows:: Defining multitable rows, with examples. +@end menu + +@node Multitable Column Widths +@subsection Multitable Column Widths +@cindex Multitable column widths +@cindex Column widths, defining for multitables +@cindex Widths, defining multitable column + +You can define the column widths for a multitable in two ways: as +fractions of the line length; or with a prototype row. Mixing the two +methods is not supported. In either case, the widths are defined +entirely on the same line as the @code{@@multitable} command. + +@enumerate +@item +@findex columnfractions +@cindex Line length, column widths as fraction of +To specify column widths as fractions of the line length, write +@code{@@columnfractions} and the decimal numbers (presumably less than +1; a leading zero is allowed and ignored) after the +@code{@@multitable} command, as in: + +@example +@@multitable @@columnfractions .33 .33 .33 +@end example + +The fractions need not add up exactly to 1.0, as these do not. This +allows you to produce tables that do not need the full line length. + +@item +@cindex Prototype row, column widths defined by +To specify a prototype row, write the longest entry for each column +enclosed in braces after the @code{@@multitable} command. For example: + +@example +@@multitable @{some text for column one@} @{for column two@} +@end example + +@noindent +The first column will then have the width of the typeset `some text for +column one', and the second column the width of `for column two'. + +The prototype entries need not appear in the table itself. + +Although we used simple text in this example, the prototype entries can +contain Texinfo commands; markup commands such as @code{@@code} are +particularly likely to be useful. + +@end enumerate + + +@node Multitable Rows +@subsection Multitable Rows + +@cindex Multitable rows +@cindex Rows, of a multitable + +@findex item +@findex tab +After the @code{@@multitable} command defining the column widths (see +the previous section), you begin each row in the body of a multitable +with @code{@@item}, and separate the column entries with @code{@@tab}. +Line breaks are not special within the table body, and you may break +input lines in your source file as necessary. + +@findex headitem +@cindex Heading row, in table +@cindex @code{<thead>} HTML/XML tag +You can also use @code{@@headitem} instead of @code{@@item} to produce +a @dfn{heading row}. The @TeX{} output for such a row is in bold, and +the HTML and Docbook output uses the @code{<thead>} tag. In Info, the +heading row is followed by a separator line made of dashes (@samp{-} +characters). + +@findex headitemfont +@cindex Font for multitable heading rows +The command @code{@@headitemfont} can be used in templates when the +entries in a @code{@@headitem} row need to be used in a template. It +is a synonym for @code{@@b}, but using @code{@@headitemfont} avoids +any dependency on that particular font style, in case we provide a way +to change it in the future. + +Here is a complete example of a multi-column table (the text is from +@cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows, +emacs, The GNU Emacs Manual}): + +@example +@@multitable @@columnfractions .15 .45 .4 +@@headitem Key @@tab Command @@tab Description +@@item C-x 2 +@@tab @@code@{split-window-vertically@} +@@tab Split the selected window into two windows, +with one above the other. +@@item C-x 3 +@@tab @@code@{split-window-horizontally@} +@@tab Split the selected window into two windows +positioned side by side. +@@item C-Mouse-2 +@@tab +@@tab In the mode line or scroll bar of a window, +split that window. +@@end multitable +@end example + +@noindent produces: + +@multitable @columnfractions .15 .45 .4 +@headitem Key @tab Command @tab Description +@item C-x 2 +@tab @code{split-window-vertically} +@tab Split the selected window into two windows, +with one above the other. +@item C-x 3 +@tab @code{split-window-horizontally} +@tab Split the selected window into two windows +positioned side by side. +@item C-Mouse-2 +@tab +@tab In the mode line or scroll bar of a window, +split that window. +@end multitable + + +@node Special Displays +@chapter Special Displays +@cindex Special displays + +The commands in this chapter allow you to write text that is specially +displayed (output format permitting), outside of the normal document +flow. + +One set of such commands is for creating ``floats'', that is, figures, +tables, and the like, set off from the main text, possibly numbered, +captioned, and/or referred to from elsewhere in the document. Images +are often included in these displays. + +Another group of commands is for creating footnotes in Texinfo. + +@menu +* Floats:: Figures, tables, and the like. +* Images:: Including graphics and images. +* Footnotes:: Writing footnotes. +@end menu + + +@node Floats +@section Floats +@cindex Floats, in general + +A @dfn{float} is a display which is set off from the main text. It is +typically labeled as being a ``Figure'', ``Table'', ``Example'', or +some similar type. + +@cindex Floating, not yet implemented +A float is so-named because, in principle, it can be moved to the +bottom or top of the current page, or to a following page, in the +printed output. (Floating does not make sense in other output +formats.) In the present version of Texinfo, however, this floating +is unfortunately not yet implemented. Instead, the floating material +is simply output at the current location, more or less as if it were +an @code{@@group} (@pxref{@code{@@group}}). + +@menu +* @code{@@float}:: Producing floating material. +* @code{@@caption @@shortcaption}:: Specifying descriptions for floats. +* @code{@@listoffloats}:: A table of contents for floats. +@end menu + + +@node @code{@@float} +@subsection @code{@@float} [@var{type}][,@var{label}]: Floating Material + +@anchor{float}@c old name +@findex float +@cindex Float environment + +To produce floating material, enclose the material you want to be +displayed separate between @code{@@float} and @code{@@end float} +commands, on lines by themselves. + +Floating material often uses @code{@@image} to display an +already-existing graphic (@pxref{Images}), or @code{@@multitable} to +display a table (@pxref{Multi-column Tables}). However, the contents +of the float can be anything. Here's an example with simple text: + +@example +@@float Figure,fig:ex1 +This is an example float. +@@end float +@end example + +@noindent And the output: + +@float Figure,fig:ex1 +This is an example float. +@end float + +As shown in the example, @code{@@float} takes two arguments (separated +by a comma), @var{type} and @var{label}. Both are optional. + +@table @var +@item type +Specifies the sort of float this is; typically a word such as +``Figure'', ``Table'', etc. If this is not given, and @var{label} is, +any cross-referencing will simply use a bare number. + +@item label +Specifies a cross-reference label for this float. If given, this +float is automatically given a number, and will appear in any +@code{@@listoffloats} output (@pxref{@code{@@listoffloats}}). Cross +references to @var{label} are allowed. + +@cindex Floats, making unnumbered +@cindex Unnumbered float, creating +On the other hand, if @var{label} is not given, then the float will +not be numbered and consequently will not appear in the +@code{@@listoffloats} output or be cross-referenceable. +@end table + +@noindent Ordinarily, you specify both @var{type} and @var{label}, to get a +labeled and numbered float. + +@cindex Floats, numbering of +@cindex Numbering of floats +In Texinfo, all floats are numbered in the same way: with the chapter +number (or appendix letter), a period, and the float number, which +simply counts 1, 2, 3, @dots{}, and is reset at each chapter. Each +float type is counted independently. + +Floats within an @code{@@unnumbered}, or outside of any chapter, are +simply numbered consecutively from 1. + +These numbering conventions are not, at present, changeable. + + +@node @code{@@caption @@shortcaption} +@subsection @code{@@caption} & @code{@@shortcaption} + +@anchor{caption shortcaption}@c old name +@findex caption +@findex shortcaption +@cindex Captions, for floats +@cindex Short captions, for lists of floats + +You may write a @code{@@caption} anywhere within a @code{@@float} +environment, to define a caption for the float. It is not allowed in +any other context. @code{@@caption} takes a single argument, enclosed +in braces. Here's an example: + +@example +@@float +An example float, with caption. +@@caption@{Caption for example float.@} +@@end float +@end example + +@noindent The output is: + +@float +An example float, with caption. +@caption{Caption for example float.} +@end float + +@code{@@caption} can appear anywhere within the float; it is not +processed until the @code{@@end float}. The caption text is usually a +sentence or two, but may consist of several paragraphs if necessary. + +In the output, the caption always appears below the float; this is not +currently changeable. It is preceded by the float type and/or number, +as specified to the @code{@@float} command (see the previous section). + +The @code{@@shortcaption} command likewise may be used only within +@code{@@float}, and takes a single argument in braces. The short +caption text is used instead of the caption text in a list of floats +(see the next section). Thus, you can write a long caption for the +main document, and a short title to appear in the list of floats. For +example: + +@example +@@float +... as above ... +@@shortcaption@{Text for list of floats.@} +@@end float +@end example + +The text for @code{@@shortcaption} may not contain comments +(@code{@@c}), verbatim text (@code{@@verb}), environments such as +@code{@@example}, footnotes (@code{@@footnote}) or other complex +constructs. The same constraints apply to @code{@@caption} unless +there is a @code{@@shortcaption}. + + +@node @code{@@listoffloats} +@subsection @code{@@listoffloats}: Tables of Contents for Floats + +@anchor{listoffloats}@c old name +@findex listoffloats +@cindex List of floats +@cindex Floats, list of +@cindex Table of contents, for floats + +You can write a @code{@@listoffloats} command to generate a list of +floats for a given float type (@pxref{@code{@@float}}), analogous to +the document's overall table of contents. Typically, it is written in +its own @code{@@unnumbered} node to provide a heading and structure, +rather like @code{@@printindex} (@pxref{Printing Indices & Menus}). + +@code{@@listoffloats} takes one optional argument, the float type. +Here's an example: + +@example +@@node List of Figures +@@unnumbered List of Figures +@@listoffloats Figure +@end example + +@noindent And here's what the output from @code{@@listoffloats} +looks like, given the example figure earlier in this chapter (the Info +output is formatted as a menu): + +@display +@ifinfo +* Figure 12.1: fig:ex1. +@end ifinfo +@ifnotinfo +@listoffloats Figure +@end ifnotinfo +@end display + +Without any argument, @code{@@listoffloats} generates a list of floats +for which no float type was specified, i.e., no first argument to the +@code{@@float} command (@pxref{@code{@@float}}). + +Each line in the list of floats contains the float type (if any), +the float number, and the caption, if any---the @code{@@shortcaption} +argument, if it was specified, else the @code{@@caption} argument. +In Info, the result is a menu where each float can be selected. In +HTML, each line is a link to the float. In printed output, the page +number is included. + +Unnumbered floats (those without cross-reference labels) are omitted +from the list of floats. + + +@node Images +@section Inserting Images + +@cindex Images, inserting +@cindex Pictures, inserting +@findex image + +You can insert an image given in an external file with the +@code{@@image} command. Although images can be used anywhere, +including the middle of a paragraph, we describe them in this chapter +since they are most often part of a displayed figure or example. + +@menu +* Image Syntax:: +* Image Scaling:: +@end menu + + +@node Image Syntax +@subsection Image Syntax + +Here is the synopsis of the @code{@@image} command: + +@example +@@image@{@var{filename}@r{[,} @var{width}@r{[,} @var{height}@r{[,} @var{alttext}@r{[, }@var{extension}@r{]]]]}@} +@end example + +@cindex Formats for images +@cindex Image formats +The @var{filename} argument is mandatory, and must not have an +extension, because the different processors support different formats: + +@itemize @bullet +@item +@pindex eps image format +@TeX{} (DVI output) reads the file @file{@var{filename}.eps} +(Encapsulated PostScript format). + +@item +@pindex pdftex@r{, and images} +@pindex png image format +@pindex jpeg image format +@pindex pdf image inclusions +pdf@TeX{} reads @file{@var{filename}.pdf}, @file{@var{filename}.png}, +@file{@var{filename}.jpg}, or @file{@var{filename}.jpeg} (in that +order). It also tries uppercase versions of the extensions. The PDF +format does not support EPS images, so such must be converted first. + +@item +For Info, @code{makeinfo} includes @file{@var{filename}.txt} verbatim +(more or less as if it were in @code{@@verbatim}). The Info output +may also include a reference to @file{@var{filename}.png} or +@file{@var{filename}.jpg}. (See below.) + +@item +For HTML, @code{makeinfo} outputs a reference to +@file{@var{filename}.png}, @file{@var{filename}.jpg}, +@file{@var{filename}.jpeg} or @file{@var{filename}.gif} (in that +order). If none of those exist, it gives an error, and outputs a +reference to @file{@var{filename}.jpg} anyway. + +@item +@cindex SVG images, used in Docbook +For Docbook, @code{makeinfo} outputs references to +@file{@var{filename}.eps}, @file{@var{filename}.gif} +@file{@var{filename}.jpeg}, @file{@var{filename}.jpg}, +@file{@var{filename}.pdf}, @file{@var{filename}.png} and +@file{@var{filename}.svg}, for every file found. Also, +@file{@var{filename}.txt} is included verbatim, if present. (The +subsequent Docbook processor is supposed to choose the appropriate one.) + +@item +For Info and HTML output, @code{makeinfo} uses the optional fifth +argument @var{extension} to @code{@@image} for the filename extension, +if it is specified and the file is found. Any leading period should +be included in @var{extension}. For example: + +@pindex XPM image format +@example +@@image@{foo,,,,.xpm@} +@end example + +@end itemize + +If you want to install image files for use by Info readers too, we +recommend putting them in a subdirectory like @samp{@var{foo}-figures} +for a package @var{foo}. Copying the files into +@code{$(infodir)/@var{foo}-figures/} should be done in your +@code{Makefile}. + +The @var{width} and @var{height} arguments are described in the next +section. + +For @TeX{} output, if an image is the only thing in a paragraph it +will ordinarily be displayed on a line by itself, respecting the +current environment indentation, but without the normal paragraph +indentation. If you want it centered, use @code{@@center} +(@pxref{@code{@@titlefont @@center @@sp}}). + +@cindex Alt attribute for images +@cindex Images, alternate text for +@findex @sortas{-} -@r{ (in image alt string)} +For HTML output, @code{makeinfo} sets the @dfn{alt attribute} for +inline images to the optional @var{alttext} (fourth) argument to +@code{@@image}, if supplied. If not supplied, @code{makeinfo} uses +the full file name of the image being displayed. The @var{alttext} is +processed as Texinfo text, so special characters such as @samp{"} and +@samp{<} and @samp{&} are escaped in the HTML output; also, you can +get an empty @code{alt} string with @code{@@-} (a command that +produces no output; @pxref{@code{@@- @@hyphenation}}). + +For Info output, the @code{alt} string is also processed as Texinfo +text and output. In this case, @samp{\} is escaped as @samp{\\} and +@samp{"} as @samp{\"}; no other escapes are done. + +In Info output, @code{makeinfo} writes a reference to the binary image +file (trying @var{filename} suffixed with @file{@var{extension}}, +@file{@var{.extension}}, @file{.png}, or @file{.jpg}, in that order) +if one exists. It also literally includes the @file{.txt} file if one +exists. This way, Info readers which can display images (such as the +Emacs Info browser, running under X) can do so, whereas Info readers +which can only use text (such as the standalone Info reader) can +display the textual version. + +@cindex @samp{^@@^H} for images in Info +The implementation of this is to put the following construct into the +Info output: + +@example +^@@^H[image src="@var{binaryfile}" text="@var{txtfile}" + alt="@var{alttext} ... ^@@^H] +@end example + +@noindent where @samp{^@@} and @samp{^H} stand for the actual null and +backspace control characters. If one of the files is not present, the +corresponding argument is omitted. + +The reason for mentioning this here is that older Info browsers (this +feature was introduced in Texinfo version 4.6) will display the above +literally, which, although not pretty, should not be harmful. + + +@node Image Scaling +@subsection Image Scaling + +@cindex Images, scaling +@cindex Scaling images +@cindex Width of images +@cindex Height of images +@cindex Aspect ratio of images +@cindex Distorting images +The optional @var{width} and @var{height} arguments to the +@code{@@image} command (see the previous section) specify the size to +which to scale the image. They are only taken into account in @TeX{}. +If neither is specified, the image is presented in its natural size +(given in the file); if only one is specified, the other is scaled +proportionately; and if both are specified, both are respected, thus +likely distorting the original image by changing its aspect ratio. + +@cindex Dimensions and image sizes +The @var{width} and @var{height} may be specified using any valid @TeX{} +dimension, namely: + +@table @asis +@item pt +@cindex Points (dimension) +point (72.27pt = 1in) +@item pc +@cindex Picas +pica (1pc = 12pt) +@item bp +@cindex Big points +big point (72bp = 1in) +@item in +@cindex Inches +inch +@item cm +@cindex Centimeters +centimeter (2.54cm = 1in) +@item mm +@cindex Millimeters +millimeter (10mm = 1cm) +@item dd +@cindex Did@^ot points +did@^ot point (1157dd = 1238pt) +@item cc +@cindex Ciceros +cicero (1cc = 12dd) +@item sp +@cindex Scaled points +scaled point (65536sp = 1pt) +@end table + +@pindex ridt.eps +For example, the following will scale a file @file{ridt.eps} to one +inch vertically, with the width scaled proportionately: + +@example +@@image@{ridt,,1in@} +@end example + +@pindex epsf.tex +For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be +installed somewhere that @TeX{} can find it. (The standard location is +@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a +root of your @TeX{} directory tree.) This file is included in the +Texinfo distribution and is also available from +@uref{ftp://tug.org/tex/epsf.tex}, among other places. + +@code{@@image} can be used within a line as well as for displayed +figures. Therefore, if you intend it to be displayed, be sure to leave +a blank line before the command, or the output will run into the +preceding text. + +Image scaling is presently implemented only in @TeX{}, not in HTML or +any other sort of output. + + +@node Footnotes +@section Footnotes +@cindex Footnotes +@findex footnote + +A @dfn{footnote} is for a reference that documents or elucidates the +primary text.@footnote{A footnote should complement or expand upon the +primary text, but a reader should not need to read a footnote to +understand the primary text. For a thorough discussion of footnotes, +see @cite{The Chicago Manual of Style}, which is published by the +University of Chicago Press.} + +Footnotes are distracting; use them sparingly at most, and it is best +to avoid them completely. Standard bibliographical references are +usually better placed in a bibliography at the end of a document +instead of in footnotes throughout. + +@menu +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. +@end menu + + +@node Footnote Commands +@subsection Footnote Commands + +In Texinfo, footnotes are created with the @code{@@footnote} command. +This command is followed immediately by a left brace, then by the text +of the footnote, and then by a terminating right brace. Footnotes may +be of any length (they will be broken across pages if necessary), but +are usually short. The template is: + +@example +ordinary text@@footnote@{@var{text of footnote}@} +@end example + +As shown here, the @code{@@footnote} command should come right after the +text being footnoted, with no intervening space; otherwise, the footnote +marker might end up starting a line. + +For example, this clause is followed by a sample footnote@footnote{Here +is the sample footnote.}; in the Texinfo source, it looks like +this: + +@example +@dots{}a sample footnote@@footnote@{Here is the sample +footnote.@}; in the Texinfo source@dots{} +@end example + +As you can see, this source includes two punctuation marks next to +each other; in this case, @samp{.@};} is the sequence. This is normal +(the first ends the footnote and the second belongs to the sentence +being footnoted), so don't worry that it looks odd. (Another style, +perfectly acceptable, is to put the footnote after punctuation +belonging to the sentence, as in @samp{;@@footnote@{...}.) + +In a printed manual or book, the reference mark for a footnote is a +small, superscripted number; the text of the footnote appears at the +bottom of the page, below a horizontal line. + +In Info, the reference mark for a footnote is a pair of parentheses +with the footnote number between them, like this: @samp{(1)}. The +reference mark is followed by a cross-reference link to the footnote +text if footnotes are put in separate nodes (@pxref{Footnote Styles}). + +In the HTML output, footnote references are generally marked with a +small, superscripted number which is rendered as a hypertext link to +the footnote text. + +@cindex Critical editions +@cindex Nested footnotes +Footnotes cannot be nested, and cannot appear in section headings of +any kind or other ``unusual'' places. + +A final tip: footnotes in the argument of an @code{@@item} command for +an @code{@@table} must be entirely on the same line as the +@code{@@item} (as usual). @xref{Two-column Tables}. + + +@node Footnote Styles +@subsection Footnote Styles + +Info has two footnote styles, which determine where the text of the +footnote is located: + +@itemize @bullet +@cindex @samp{@r{End}} node footnote style +@item +In the `End' node style, all the footnotes for a single node are +placed at the end of that node. The footnotes are separated from the +rest of the node by a line of dashes with the word @samp{Footnotes} +within it. Each footnote begins with an @samp{(@var{n})} reference +mark. + +@need 700 +@noindent +Here is an example of the Info output for a single footnote in the +end-of-node style: + +@example +@group +--------- Footnotes --------- + +(1) Here is a sample footnote. +@end group +@end example + +@cindex @samp{@r{Separate}} footnote style +@item +In the `Separate' node style, all the footnotes for a single +node are placed in an automatically constructed node of +their own. In this style, a ``footnote reference'' follows +each @samp{(@var{n})} reference mark in the body of the +node. The footnote reference is actually a cross-reference +which you use to reach the footnote node. + +The name of the node with the footnotes is constructed +by appending @w{@samp{-Footnotes}} to the name of the node +that contains the footnotes. (Consequently, the footnotes' +node for the @file{Footnotes} node is +@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an +`Up' node pointer that leads back to its parent node. + +@noindent +Here is how the first footnote in this manual looks after being +formatted for Info in the separate node style: + +@smallexample +@group +File: texinfo.info Node: Overview-Footnotes, Up: Overview + +(1) The first syllable of "Texinfo" is pronounced like "speck", not +"hex". @dots{} +@end group +@end smallexample +@end itemize + +Unless your document has long and important footnotes (as in, say, +Gibbon's @cite{Decline and Fall @dots{}}), we recommend the @samp{end} +style, as it is simpler for readers to follow. + +@findex footnotestyle +Use the @code{@@footnotestyle} command to specify an Info file's +footnote style. Write this command at the beginning of a line followed +by an argument, either @samp{end} for the end node style or +@samp{separate} for the separate node style. + +@need 700 +For example, + +@example +@@footnotestyle end +@end example +@noindent +or +@example +@@footnotestyle separate +@end example + +Write a @code{@@footnotestyle} command before or shortly after the +end-of-header line at the beginning of a Texinfo file. (You should +include any @code{@@footnotestyle} command between the start-of-header +and end-of-header lines, so the region formatting commands will format +footnotes as specified.) + +In HTML, when the footnote style is @samp{end}, or if the output is +not split, footnotes are put at the end of the output. If set to +@samp{separate}, and the output is split, they are placed in a +separate file. + + +@node Indices +@chapter Indices +@cindex Indices + +Using Texinfo, you can generate indices without having to sort and +collate entries manually. In an index, the entries are listed in +alphabetical order, together with information on how to find the +discussion of each entry. In a printed manual, this information +consists of page numbers. In an Info file, this information is a menu +entry leading to the first node referenced. + +Texinfo provides several predefined kinds of index: an index for +functions, an index for variables, an index for concepts, and so on. +You can combine indices or use them for other than their canonical +purpose. Lastly, you can define your own new indices. + +@menu +* Predefined Indices:: Use different indices for different kinds + of entries. +* Indexing Commands:: How to make an index entry. +* Index Entries:: Choose different words for index entries. +* Printing Indices & Menus:: How to print an index in hardcopy and + generate index menus in Info. +* Combining Indices:: How to combine indices. +* New Indices:: How to define your own indices. +@end menu + + +@node Predefined Indices +@section Predefined Indices + +Texinfo provides six predefined indices. Here are their nominal +meanings, abbreviations, and the corresponding index entry commands: + +@table @samp +@item cp +@cindex @code{cp} (concept) index +@findex cindex +(@code{@@cindex}) concept index, for general concepts. +@item fn +@cindex @code{fn} (function) index +@findex findex +(@code{@@findex}) function index, for function and function-like +names (such as entry points of libraries). +@item ky +@cindex @code{ky} (keystroke) index +@findex kindex +(@code{@@kindex}) keystroke index, for keyboard commands. +@item pg +@cindex @code{pg} (program) index +@findex pindex +(@code{@@pindex}) program index, for names of programs. +@item tp +@cindex @code{tp} (data type) index +@findex tindex +(@code{@@tindex}) data type index, for type names (such as structures +defined in header files). +@item vr +@cindex @code{vr} (variable) index +@findex vindex +(@code{@@vindex}) variable index, for variable names (such as global +variables of libraries). +@end table + +@noindent +Not every manual needs all of these, and most manuals use only two or +three at most. The present manual, for example, has two indices: a +concept index and an @@-command index (that is actually the function +index but is called a command index in the chapter heading). + +You are not required to use the predefined indices strictly for their +canonical purposes. For example, suppose you wish to index some C +preprocessor macros. You could put them in the function index along +with actual functions, just by writing @code{@@findex} commands for +them; then, when you print the ``Function Index'' as an unnumbered +chapter, you could give it the title `Function and Macro Index' and +all will be consistent for the reader. + +On the other hand, it is best not to stray too far from the meaning of +the predefined indices. Otherwise, in the event that your text is +combined with other text from other manuals, the index entries will +not match up. Instead, define your own new index (@pxref{New +Indices}). + +We recommend having a single index in the final document whenever +possible, however many source indices you use, since then readers have +only one place to look. Two or more source indices can be combined +into one output index using the @code{@@synindex} or +@code{@@syncodeindex} commands (@pxref{Combining Indices}). + + +@node Indexing Commands +@section Defining the Entries of an Index + +@cindex Defining indexing entries +@cindex Index entries +@cindex Entries for an index +@cindex Specifying index entries +@cindex Creating index entries + +The data to make an index come from many individual indexing commands +scattered throughout the Texinfo source file. Each command says to add +one entry to a particular index; after formatting, the index will give +the current page number or node name as the reference. + +An index entry consists of an indexing command at the beginning of a +line followed, on the rest of the line, by the entry. + +For example, this section begins with the following five entries for +the concept index: + +@example +@@cindex Defining indexing entries +@@cindex Index entries, defining +@@cindex Entries for an index +@@cindex Specifying index entries +@@cindex Creating index entries +@end example + +Each predefined index has its own indexing command---@code{@@cindex} +for the concept index, @code{@@findex} for the function index, and so +on, as listed in the previous section. + +Index entries should precede the visible material that is being +indexed. For instance: + +@example +@@cindex hello +Hello, there! +@end example + +@noindent Among other reasons, that way following indexing links (in +whatever context) ends up before the material, where readers want to +be, instead of after. + +Try to avoid using a colon in an index entry, as this may confuse some +Info readers. @xref{Menu Parts} for more information about the +structure of a menu entry. +@c At the time of writing, it always works in standalone info, and a +@c single colon not followed by a space works in Emacs. + +@cindex Index font types +By default, entries for a concept index are printed in a small roman +font and entries for the other indices are printed in a small +@code{@@code} font. You may change the way part of an entry is +printed with the usual Texinfo commands, such as @code{@@file} for +file names (@pxref{Marking Text}), and @code{@@r} for the normal roman +font (@pxref{Fonts}). + +@findex sortas +@cindex sort keys for index entries +@cindex index sorting +For the printed output, you may specify an explicit sort key for an +index entry using @code{@@sortas} immediately following the index +command. For example: @samp{@@findex @@sortas@{\@} \ @@r@{(literal +\ in @@code@{@@@@math@})} sorts the index entry this produces under +backslash. + +@vindex txiindexbackslashignore +@vindex txiindexhyphenignore +@vindex txiindexlessthanignore +@vindex txiindexatsignignore +To reduce the quantity of sort keys you need to provide explicitly, +you may choose to ignore certain characters in index entries +for the purposes of sorting. The characters that you can +currently choose to ignore are @samp{\}, @samp{-}, @samp{<} +and @samp{@@}, which are ignored by giving as an argument to the +@code{@@set} command, respectively, @code{txiindexbackslashignore}, +@code{txiindexhyphenignore}, @code{txiindexlessthanignore} and +@code{txiindexatsignignore}. For example, specifying @samp{@@set +txiindexbackslashignore} causes the @samp{\mathopsup} entry in the +index for this manual to be sorted as if it were @samp{mathopsup}, +so that it appears among the other entries beginning `M'. + + +@node Index Entries +@section Making Index Entries +@cindex Index entries, making +@cindex Entries, making index + +@cindex Writing index entries +@cindex Index entries, advice on writing +@cindex Advice on writing entries +@cindex Capitalization of index entries +Concept index entries consist of text. The best way to write an index +is to devise entries which are terse yet clear. If you can do this, +the index usually looks better if the entries are written just as they +would appear in the middle of a sentence, that is, capitalizing only +proper names and acronyms that always call for uppercase letters. +This is the case convention we use in most GNU manuals' indices. + +If you don't see how to make an entry terse yet clear, make it longer +and clear---not terse and confusing. If many of the entries are +several words long, the index may look better if you use a different +convention: to capitalize the first word of each entry. Whichever +case convention you use, use it consistently. + +In any event, do not ever capitalize a case-sensitive name such as a C +or Lisp function name or a shell command; that would be a spelling +error. Entries in indices other than the concept index are symbol +names in programming languages, or program names; these names are +usually case-sensitive, so likewise use upper- and lowercase as +required. + +@cindex Unique index entries +It is a good idea to make index entries unique wherever feasible. +That way, people using the printed output or online completion of +index entries don't see undifferentiated lists. Consider this an +opportunity to make otherwise-identical index entries be more +specific, so readers can more easily find the exact place they are +looking for. + + +When you are making index entries, it is good practice to think of the +different ways people may look for something. Different people +@emph{do not} think of the same words when they look something up. A +helpful index will have items indexed under all the different words +that people may use. For example, one reader may think it obvious +that the two-letter names for indices should be listed under +``Indices, two-letter names, since ``Indices'' are the general +concept. But another reader may remember the specific concept of +two-letter names and search for the entry listed as ``Two letter names +for indices''. A good index will have both entries and will help both +readers. + +Like typesetting, the construction of an index is a skilled art, the +subtleties of which may not be appreciated until you need to do it +yourself. + + +@node Printing Indices & Menus +@section Printing Indices and Menus +@cindex Printing an index +@cindex Indices, printing and menus +@cindex Generating menus with indices +@cindex Menus generated with indices + +To print an index means to include it as part of a manual or Info file. +This does not happen automatically just because you use @code{@@cindex} +or other index-entry generating commands in the Texinfo file; those just +cause the raw data for the index to be accumulated. To generate an +index, you must include the @code{@@printindex} command at the place in +the document where you want the index to appear. Also, as part of the +process of creating a printed manual, you must run a program called +@code{texindex} (@pxref{Hardcopy}) to sort the raw data to produce a +sorted index file. The sorted index file is what is actually used to +print the index. + +Texinfo offers six separate types of predefined index, which suffice +in most cases. @xref{Indices}, for information on this, as well +defining your own new indices, combining indices, and, most +importantly advice on writing the actual index entries. This section +focuses on printing indices, which is done with the +@code{@@printindex} command. + +@findex printindex +@code{@@printindex} takes one argument, a two-letter index +abbreviation. It reads the corresponding sorted index file (for +printed output), and formats it appropriately into an index. + +The @code{@@printindex} command does not generate a chapter heading +for the index, since different manuals have different needs. +Consequently, you should precede the @code{@@printindex} command with +a suitable section or chapter command (usually @code{@@appendix} or +@code{@@unnumbered}) to supply the chapter heading and put the index +into the table of contents. Precede the chapter heading with an +@code{@@node} line as usual. + +For example: + +@smallexample +@group +@@node Variable Index +@@unnumbered Variable Index + +@@printindex vr +@end group + +@group +@@node Concept Index +@@unnumbered Concept Index + +@@printindex cp +@end group +@end smallexample + +If you have more than one index, we recommend placing the concept index last. + +@itemize +@item +In printed output, @code{@@printindex} produces a traditional +two-column index, with dot leaders between the index terms and page +numbers. + +@item +In Info output, @code{@@printindex} produces a special menu containing +the line number of the entry, relative to the start of the node. Info +readers can use this to go to the exact line of an entry, not just the +containing node. (Older Info readers will just go to the node.) +Here's an example: + +@smallexample +* First index entry: Top. (line 7) +@end smallexample + +@noindent The actual number of spaces is variable, to right-justify +the line number; it's been reduced here to make the line fit in the +printed manual. + +@item +In plain text output, @code{@@printindex} produces the same menu, but +the line numbers are relative to the start of the file, since that's +more convenient for that format. + +@item +In HTML output, @code{@@printindex} produces links to the index +entries. + +@item +In XML and Docbook output, it simply records the index to be printed. +@end itemize + + +@node Combining Indices +@section Combining Indices +@cindex Combining indices +@cindex Indices, combining them + +Sometimes you will want to combine two disparate indices such as +functions and concepts, perhaps because you have few enough entries +that a separate index would look silly. + +You could put functions into the concept index by writing +@code{@@cindex} commands for them instead of @code{@@findex} commands, +and produce a consistent manual by printing the concept index with the +title `Function and Concept Index' and not printing the `Function +Index' at all; but this is not a robust procedure. It works only if +your document is never included as part of another document that is +designed to have a separate function index; if your document were to +be included with such a document, the functions from your document and +those from the other would not end up together. Also, to make your +function names appear in the right font in the concept index, you +would need to enclose every one of them between the braces of +@code{@@code}. + +@menu +* @code{@@syncodeindex}:: How to merge two indices, using @code{@@code} + font for the merged-from index. +* @code{@@synindex}:: How to merge two indices, using the + roman font for the merged-from index. +@end menu + + +@node @code{@@syncodeindex} +@subsection @code{@@syncodeindex}: Combining indices using @code{@@code} + +@anchor{syncodeindex}@c old name +@findex syncodeindex + +When you want to combine functions and concepts into one index, you +should index the functions with @code{@@findex} and index the concepts +with @code{@@cindex}, and use the @code{@@syncodeindex} command to +redirect the function index entries into the concept index. + +The @code{@@syncodeindex} command takes two arguments; they are the name +of the index to redirect, and the name of the index to redirect it to. +The template looks like this: + +@example +@@syncodeindex @var{from} @var{to} +@end example + +@cindex Predefined names for indices +@cindex Two letter names for indices +@cindex Indices, two letter names +@cindex Names for indices +For this purpose, the indices are given two-letter names: + +@table @samp +@item cp +concept index +@item fn +function index +@item vr +variable index +@item ky +key index +@item pg +program index +@item tp +data type index +@end table + +Write a @code{@@syncodeindex} command before or shortly after the +end-of-header line at the beginning of a Texinfo file. For example, +to merge a function index with a concept index, write the +following: + +@example +@@syncodeindex fn cp +@end example + +@noindent +This will cause all entries designated for the function index to merge +in with the concept index instead. + +To merge both a variables index and a function index into a concept +index, write the following: + +@example +@group +@@syncodeindex vr cp +@@syncodeindex fn cp +@end group +@end example + +@cindex Fonts for indices +The @code{@@syncodeindex} command puts all the entries from the `from' +index (the redirected index) into the @code{@@code} font, overriding +whatever default font is used by the index to which the entries are +now directed. This way, if you direct function names from a function +index into a concept index, all the function names are printed in the +@code{@@code} font as you would expect. + + +@node @code{@@synindex} +@subsection @code{@@synindex}: Combining indices + +@anchor{synindex}@c old name +@findex synindex + +The @code{@@synindex} command is nearly the same as the +@code{@@syncodeindex} command, except that it does not put the `from' +index entries into the @code{@@code} font; rather it puts them in the +roman font. Thus, you use @code{@@synindex} when you merge a concept +index into a function index. + +@xref{Printing Indices & Menus}, for information about printing an index +at the end of a book or creating an index menu in an Info file. + + +@node New Indices +@section Defining New Indices + +@cindex Defining new indices +@cindex Indices, defining new +@cindex New index defining +@findex defindex +@findex defcodeindex + +In addition to the predefined indices (@pxref{Predefined Indices}), +you may use the @code{@@defindex} and @code{@@defcodeindex} commands +to define new indices. These commands create new indexing @@-commands +with which you mark index entries. The @code{@@defindex} command is +used like this: + +@example +@@defindex @var{name} +@end example + +New index names are usually two-letter words, such as @samp{au}. +For example: + +@example +@@defindex au +@end example + +This defines a new index, called the @samp{au} index. At the same +time, it creates a new indexing command, @code{@@auindex}, that you +can use to make index entries. Use this new indexing command just as +you would use a predefined indexing command. + +For example, here is a section heading followed by a concept index +entry and two @samp{au} index entries. + +@example +@@section Cognitive Semantics +@@cindex kinesthetic image schemas +@@auindex Johnson, Mark +@@auindex Lakoff, George +@end example + +@noindent +(Evidently, @samp{au} serves here as an abbreviation for ``author''.) + +Texinfo constructs the new indexing command by concatenating the name +of the index with @samp{index}; thus, defining an @samp{xy} index +leads to the automatic creation of an @code{@@xyindex} command. + +Use the @code{@@printindex} command to print the index, as you do with +the predefined indices. For example: + +@example +@group +@@node Author Index +@@unnumbered Author Index + +@@printindex au +@end group +@end example + +The @code{@@defcodeindex} is like the @code{@@defindex} command, +except that, in the printed output, it prints entries in an +@code{@@code} font by default instead of a roman font. + +You should define new indices before the end-of-header line of a +Texinfo file, and (of course) before any @code{@@synindex} or +@code{@@syncodeindex} commands (@pxref{Texinfo File Header}). + +As mentioned earlier (@pxref{Predefined Indices}), we recommend having +a single index in the final document whenever possible, however many +source indices you use, since then readers have only one place to +look. + +When creating an index, @TeX{} creates a file whose extension is the +name of the index (@pxref{Names of index files}). Therefore you +should avoid using index names that collide with extensions used for +other purposes, such as @samp{.aux} or @samp{.xml}. +@command{makeinfo} already reports an error if a new index conflicts +well-known extension name. + + +@node Insertions +@chapter Special Insertions +@cindex Inserting special characters and symbols +@cindex Special insertions + +Texinfo provides several commands for inserting characters that have +special meaning in Texinfo, such as braces, and for other graphic +elements that do not correspond to simple characters you can type. + +@iftex +These are: + +@itemize @bullet +@item The Texinfo special characters: @samp{@@ @{@} , \ # &}. +@item Whitespace within and around a sentence. +@item Accents. +@item Dots and bullets. +@item The @TeX{} logo and the copyright symbol. +@item The euro and pounds currency symbols. +@item The degrees symbol. +@item The minus sign. +@item Mathematical expressions. +@item Glyphs for examples of programming: evaluation, macros, errors, etc. +@item Footnotes. +@end itemize +@end iftex + +@menu +* Special Characters:: Inserting @@ @{@} , \ # & +* Inserting Quote Characters:: Inserting left and right quotes, in code. +* Inserting Space:: Inserting the right amount of whitespace. +* Inserting Accents:: Inserting accents and special characters. +* Inserting Quotation Marks:: Inserting quotation marks. +* Inserting Subscripts and Superscripts:: Inserting sub/superscripts. +* Inserting Math:: Formatting mathematical expressions. +* Glyphs for Text:: Inserting dots, bullets, currencies, etc. +* Glyphs for Programming:: Indicating results of evaluation, + expansion of macros, errors, etc. +* Inserting Unicode:: Inserting a Unicode character by code point. +@end menu + + +@node Special Characters +@section Special Characters: Inserting @@ @{@} , \ # & +@anchor{Braces Atsign}@c previous names for this node +@anchor{Atsign Braces Comma} +@cindex Special characters, inserting +@cindex Commands to insert special characters + +@samp{@@} and curly braces are the basic special characters in +Texinfo. To insert these characters so they appear in text, you must +put an @samp{@@} in front of these characters to prevent Texinfo from +misinterpreting them. Alphabetic commands are also provided. + +The other characters (comma, backslash, hash, ampersand) are special +only in restricted contexts, as explained in the respective sections. + +@menu +* Inserting an Atsign:: @code{@@@@}, @code{@@atchar@{@}}. +* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l rbracechar@{@}}. +* Inserting a Comma:: , and @code{@@comma@{@}}. +* Inserting a Backslash:: \ and @code{@@backslashchar@{@}}. +* Inserting a Hashsign:: # and @code{@@hashchar@{@}}. +* Inserting an Ampersand:: & and @code{@@ampchar@{@}}. +@end menu + + +@node Inserting an Atsign +@subsection Inserting `@@' with @code{@@@@} and @code{@@atchar@{@}} +@cindex At sign, inserting +@cindex Inserting @@ @r{(literal @samp{@@})} +@findex @sortas{@@} @@ @r{(literal @samp{@@})} +@findex atchar@{@} @r{(literal @samp{@@})} + +@code{@@@@} produces a single @samp{@@} character in the output. Do +not put braces after an @code{@@@@} command. + +@code{@@atchar@{@}} also produces a single @samp{@@} character in the +output. It does need following braces, as usual for alphabetic +commands. In inline conditionals (@pxref{Inline Conditionals}), it +can be necessary to avoid using the literal @samp{@@} character in the +source (and may be clearer in other contexts). + + +@node Inserting Braces +@subsection Inserting `@{ `@}' with @code{@@@{ @@@}} and @code{@@l rbracechar@{@}} + +@findex @{ @r{(literal @samp{@{})} +@findex @} @r{(literal @samp{@}})} +@findex lbracechar@{@} @r{(literal @samp{@{})} +@findex rbracechar@{@} @r{(literal @samp{@}})} +@cindex Braces, inserting + +@code{@@@{} produces a single @samp{@{} in the output, and @code{@@@}} +produces a single @samp{@}}. Do not put braces after either an +@code{@@@{} or an @code{@@@}} command. + +@code{@@lbracechar@{@}} and @code{@@rbracechar@{@}} also produce +single @samp{@{} and @samp{@}} characters in the output. They do need +following braces, as usual for alphabetic commands. In inline +conditionals (@pxref{Inline Conditionals}), it can be +necessary to avoid using literal brace characters in the source (and +may be clearer in other contexts). + + +@node Inserting a Comma +@subsection Inserting `,' with @code{@@comma@{@}} + +@findex comma +@cindex Comma, inserting + +Ordinarily, a comma `,' is a normal character that can be simply typed +in your input where you need it. + +However, Texinfo uses the comma as a special character only in one +context: to separate arguments to those Texinfo commands, such as +@code{@@acronym} (@pxref{@code{@@acronym}}) and @code{@@xref} +(@pxref{Cross References}), as well as user-defined macros +(@pxref{Defining Macros}), which take more than one argument. + +Since a comma character would confuse Texinfo's parsing for these +commands, you must use the command @samp{@@comma@{@}} instead if you want +to pass an actual comma. Here are some examples: + +@example +@@acronym@{ABC, A Bizarre @@comma@{@}@} +@@xref@{Comma,, The @@comma@{@} symbol@} +@@mymac@{One argument@@comma@{@} containing a comma@} +@end example + +Although @samp{@@comma@{@}} can be used nearly anywhere, there is no +need for it anywhere except in this unusual case. + +(Incidentally, the name @samp{@@comma} lacks the @samp{char} suffix used +in its companion commands only for historical reasons. It didn't seem +important enough to define a synonym.) + + +@node Inserting a Backslash +@subsection Inserting `\' with @code{@@backslashchar@{@}} + +@findex backslashchar +@cindex Backslash, inserting + +Ordinarily, a backslash `\' is a normal character in Texinfo that can +be simply typed in your input where you need it. The result is to +typeset the backslash from the typewriter font. + +However, Texinfo uses the backslash as a special character in one +restricted context: to delimit formal arguments in the bodies of +user-defined macros (@pxref{Defining Macros}). + +Due to the vagaries of macro argument parsing, it is more reliable to +pass an alphabetic command that produces a backslash instead of using +a literal \. Hence @code{@@backslashchar@{@}}. Here is an example +macro call: + +@example +@@mymac@{One argument@@backslashchar@{@} with a backslash@} +@end example + +@findex \backslash +Texinfo documents may also use \ as a command character inside +@code{@@math} (@pxref{Inserting Math}). In this case, @code{@@\} or +@code{\backslash} produces a ``math'' backslash (from the math symbol +font), while @code{@@backslashchar@{@}} produces a typewriter +backslash as usual. + +Although @samp{@@backslashchar@{@}} can be used nearly anywhere, there +is no need for it except in these unusual cases. + + +@node Inserting a Hashsign +@subsection Inserting `#' with @code{@@hashchar@{@}} + +@findex hashchar@{@} @r{(literal @samp{#})} +@cindex Inserting # +@cindex Hash sign, inserting + +Ordinarily, a hash `#' is a normal character in Texinfo that can be +simply typed in your input where you need it. The result is to +typeset the hash character from the current font. + +@cindex Number sign, inserting +@cindex Octotherp, inserting +@cindex Sharp sign (not), inserting +This character has many other names, varying by locale, such as +``number sign'', ``pound'', and ``octothorp''. It is also sometimes +called ``sharp'' or ``sharp sign'' since it vaguely resembles the +musical symbol by that name. In situations where Texinfo is used, +``hash'' is the most common in our experience. + +However, Texinfo uses the hash character as a special character in one +restricted context: to introduce the so-called @code{#line} directive +and variants (@pxref{External Macro Processors}). + +So, in order to typeset an actual hash character in such a place (for +example, in a program that needs documentation about @code{#line}), +it's necessary to use @code{@@hashchar@{@}} or some other construct. +Here's an example: + +@example +@@hashchar@{@} 10 "example.c" +@end example + +Although @samp{@@hashchar@{@}} can be used nearly anywhere, there +is no need for it anywhere except this unusual case. + + +@node Inserting an Ampersand +@subsection Inserting `&' with @code{@@&} and @code{@@ampchar@{@}} + +@findex ampchar@{@} @r{(literal @samp{&})} +@cindex Inserting & +@cindex Ampersand, inserting + +Ordinarily, an ampersand `&' is a normal character in Texinfo that can be +simply typed in your input where you need it. The result is to +typeset the ampersand character. + +However, the ampersand character has a special meaning in Texinfo in +just one restricted context. In the argument to a definition command +(@pxref{Definition Commands}), Emacs Lisp keywords beginning with +ampersands are recognized and typeset specially. @xref{A Sample +Function Description,,, elisp, GNU Emacs Lisp Reference Manual}. +For example: + +@example +@@defun foo integer1 &optional integer2 &rest integers +@@code@{foo@} described here. +@@end defun +@end example + +@noindent leads to the output + +@defun foo integer1 &optional integer2 &rest integers +@code{foo} described here. +@end defun + +So, in order to typeset an ampersand in such a context (for example, in +documentation of a C++ function taking a reference as a parameter), +it's necessary to use @code{@@&} or some other construct. +Here's an example: + +@example +@@deftypefn Function int foo (@@code@{const std::vector<int>@@&@} bar) +Documentation of @@code@{foo@}. +@@end deftypefn +@end example + +@noindent This gives the output + +@deftypefn Function int foo (@code{const std::vector<int>@&} bar) +Documentation of @code{foo}. +@end deftypefn + +Although @samp{@@&} and @samp{@@ampchar@{@}} can be used nearly +anywhere, there is no need for them anywhere except this unusual case. + + +@node Inserting Quote Characters +@section Inserting Quote Characters + +@cindex Inserting quote characters +@cindex Quote characters, inserting + +As explained in the early section on general Texinfo input conventions +(@pxref{Conventions}), Texinfo source files use the ASCII character +@code{`} (96 decimal) to produce a left quote (`), and ASCII @code{'} +(39 decimal) to produce a right quote ('). Doubling these input +characters (@code{``} and @code{''}) produces double quotes (`` and +''). These are the conventions used by @TeX{}. + +This works all right for text. However, in examples of computer code, +readers are especially likely to cut and paste the text +verbatim---and, unfortunately, some document viewers will mangle these +characters. (The free PDF reader @command{xpdf} works fine, but other +PDF readers, both free and nonfree, have problems.) + +If this is a concern for you, Texinfo provides these two commands: + +@table @code +@item @@codequoteundirected @var{on-off} +@findex codequoteundirected +@cindex undirected single quote +causes the output for the @code{'} character in code environments to +be the undirected single quote, like this: +@set txicodequoteundirected on +@code{'}. +@set txicodequoteundirected off + +@item @@codequotebacktick @var{on-off} +@findex codequotebacktick +@cindex backtick +@cindex grave accent, standalone +causes the output for the @code{`} character in code environments to +be the backtick character (standalone grave accent), like this: +@set txicodequotebacktick on +@code{`}. +@set txicodequotebacktick off +@end table + +If you want these settings for only part of the document, +@code{@@codequote... off} will restore the normal behavior, as in +@code{@@codequoteundirected off}. + +These settings affect @code{@@code}, @code{@@example}, @code{@@kbd}, +@code{@@samp}, @code{@@verb}, and @code{@@verbatim}. @xref{Useful +Highlighting}. + +@vindex txicodequoteundirected@r{, obsolete variable} +@vindex txicodequotebacktick@r{, obsolete variable} +This feature used to be controlled by using @code{@@set} to change the +values of the corresponding variables @code{txicodequoteundirected} +and @code{txicodequotebacktick}; they are still supported, but the +command interface is preferred. + + +@node Inserting Space +@section Inserting Space + +@cindex Inserting space +@cindex Spacing, inserting +The following sections describe commands that control spacing of various +kinds within and after sentences. + +@menu +* Multiple Spaces:: Inserting multiple spaces. +* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. +* Ending a Sentence:: Sometimes it does. +* @code{@@frenchspacing}:: Specifying end-of-sentence spacing. +* @code{@@dmn}:: Formatting a dimension. +@end menu + + +@node Multiple Spaces +@subsection Multiple Spaces + +@cindex Multiple spaces +@cindex Whitespace, inserting +@cindex Space, inserting horizontal +@findex <space> +@findex <tab> +@findex <newline> + +Ordinarily, multiple whitespace characters (space, tab, and newline) +are collapsed into a single space. + +Occasionally, you may want to produce several consecutive spaces, +either for purposes of example (e.g., what your program does with +multiple spaces as input), or merely for purposes of appearance in +headings or lists. Texinfo supports three commands: +@code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all +of which insert a single space into the output. (Here, +@code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a +space, i.e., @samp{@@ }, @kbd{TAB} represents an actual tab character, +and @code{@@@kbd{NL}} represents an @samp{@@} character and end-of-line, +i.e., when @samp{@@} is the last character on a line.) + +For example, +@example +Spacey@@ @@ @@ @@ +example. +@end example + +@noindent produces + +@example +Spacey@ @ @ @ +example. +@end example + +Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by +@code{@@multitable} (@pxref{Multi-column Tables}). + +Do not follow any of these commands with braces. + +To produce a non-breakable space, see @ref{@code{@@tie}}. + + +@node Not Ending a Sentence +@subsection Not Ending a Sentence + +@cindex Not ending a sentence +@cindex Sentence non-ending punctuation +@cindex Periods, inserting +@cindex Spacing, in the middle of sentences +When a period, exclamation point or question mark is +at the end of a sentence, slightly more space is +inserted after it in a typeset manual. + +@findex <colon> @r{(suppress end-of-sentence space)} +@findex : +Usually, Texinfo can determine automatically when a period ends a +sentence. However, special commands are needed in some circumstances. +Use the @code{@@:} command after a period, question mark, exclamation +mark or colon that should not be followed by extra space. This is +necessary in the following situations: + +@enumerate +@item After a period that ends a lowercase abbreviation which is not at +the end of a sentences. + +@item When a parenthetical remark in the middle of a sentence (like +this one!)@: ends with a period, exclamation point or question mark, +@code{@@:} should be used after the right parenthesis. Similarly for +right brackets and right quotes (both single and double). +@end enumerate + +For example: + +@example +@samp{foo vs.@@: bar (or?)@@: baz}, +@end example + +@noindent +The first line below shows the output, and for comparison, the second +line shows the spacing when the @samp{@@:} commands were not used. + +@quotation +foo vs.@: bar (or?)@: baz@* +foo vs. bar (or?) baz +@end quotation + +@iftex +If you look carefully, you will see a bit of extraneous space after the +@samp{vs.}@: and @samp{(or?)}@:. +@end iftex + +It may help you to remember what @code{@@:} does by imagining that it +stands for an invisible lower-case character that stops a word ending in +a period. + +A few Texinfo commands force normal interword spacing, so that you +don't have to insert @code{@@:} where you otherwise would. These are +the code-like highlighting commands, @code{@@var}, @code{@@abbr}, and +@code{@@acronym} (@pxref{Useful Highlighting}). For example, in +@samp{@@code@{foo. bar@}} the period is not considered to be the end of a +sentence, and no extra space is inserted. + +@code{@@:} has no effect on the HTML or Docbook output. + + +@node Ending a Sentence +@subsection Ending a Sentence + +@cindex Ending a Sentence +@cindex Sentence ending punctuation + +@findex . @r{(end of sentence)} +@findex ! @r{(end of sentence)} +@findex ? @r{(end of sentence)} +@cindex Spacing, at ends of sentences +As mentioned above, Texinfo normally inserts additional space after +the end of a sentence. It uses the same heuristic for this as @TeX{}: +a sentence ends with a period, exclamation point, or question mark, +either preceded or followed by optional closing punctuation, and then +whitespace, and @emph{not} preceded by a capital letter. + +Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an +exclamation point, and @code{@@?}@: instead of a question mark at the +end of a sentence that does end with a capital letter. Do not put +braces after any of these commands. For example: + +@example +Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@. +Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. +@end example + +@noindent +The output follows. In printed output and Info, you can see the +desired extra whitespace after the @samp{W} in the first line. + +@quotation +Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@* +Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. +@end quotation + +In the HTML output, @code{@@.}@: is equivalent to a simple @samp{.}; +likewise for @code{@@!}@: and @code{@@?}@:. + +@cindex Closing punctuation, and sentence ending +The ``closing punctuation'' mentioned above is defined as a right +parenthesis (@samp{)}, right bracket (@samp{]}), or right quote, +either single or double (@samp{'} and @samp{''}; the many possible +additional Unicode right quotes are not included). These characters +can be thought of as invisible with respect to whether a given period +ends a sentence. (This is the same rule as @TeX{}.) For instance, +the periods in @samp{foo.) Bar} and @samp{foo.'' Bar} do end +sentences. + +The meanings of @code{@@:} and @code{@@.}, etc.@: in Texinfo are +designed to work well with the Emacs sentence motion commands +(@pxref{Sentences,,, emacs, The GNU Emacs Manual}). It may help to +imagine that the @samp{@@} in @samp{@@.}, etc., is an invisible +lower-case letter `a' which makes an upper-case letter before it +immaterial for the purposes of deciding whether the period ends the +sentence. + +A few Texinfo commands are not considered as being an abbreviation, +even though they may end with a capital letter when expanded, so that +you don't have to insert @code{@@.} and companions. Notably, this is +the case for code-like highlighting commands, @code{@@var} arguments +ending with a capital letter, @code{@@LaTeX}, and @code{@@TeX}. For +example, that sentence ended with @samp{... @@code@{@@@@TeX@}.}; +@code{@@.} was not needed. Similarly, in +@code{... @@var@{VARNAME@}. Text} the period after @var{VARNAME} ends +the sentence; there is no need to use @code{@@.}. + + +@node @code{@@frenchspacing} +@subsection @code{@@frenchspacing} @var{val}: Control Sentence Spacing + +@anchor{frenchspacing}@c old name +@findex frenchspacing +@cindex French spacing +@cindex Sentences, spacing after +@cindex Space, after sentences + +In American typography, it is traditional and correct to put extra +space at the end of a sentence. This is the default in Texinfo +(implemented in Info and printed output; for HTML, we don't try to +override the browser). In French typography (and others), this extra +space is wrong; all spaces are uniform. + +Therefore Texinfo provides the @code{@@frenchspacing} command to +control the spacing after punctuation. It reads the rest of the line +as its argument, which must be the single word @samp{on} or @samp{off} +(always these words, regardless of the language of the document). +Here is an example: + +@example +@@frenchspacing on +This is text. Two sentences. Three sentences. French spacing. + +@@frenchspacing off +This is text. Two sentences. Three sentences. Non-French spacing. +@end example + +@noindent produces: + +@frenchspacing on +This is text. Two sentences. Three sentences. French spacing. + +@frenchspacing off +This is text. Two sentences. Three sentences. Non-French spacing. + +@code{@@frenchspacing} also affects the output after @code{@@.}, +@code{@@!}, and @code{@@?} (@pxref{Ending a Sentence}). + +@code{@@frenchspacing} has no effect on the HTML or Docbook output; +for XML, it outputs a transliteration of itself (@pxref{Output +Formats}). + + +@node @code{@@dmn} +@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension + +@anchor{dmn}@c old name +@cindex Thin space between number, dimension +@cindex Dimension formatting +@cindex Format a dimension +@findex dmn + +You can use the @code{@@dmn} command to format a dimension with a +little extra space in the printed output. That is, on seeing +@code{@@dmn}, @TeX{} inserts just enough space for proper typesetting; +in other output formats, the formatting commands insert no space at +all. + +To use the @code{@@dmn} command, write the number and then follow it +immediately, with no intervening space, by @code{@@dmn}, and then by +the dimension within braces. For example, + +@example +A4 paper is 8.27@@dmn@{in@} wide. +@end example + +@noindent +produces + +@quotation +A4 paper is 8.27@dmn{in} wide. +@end quotation + +Not everyone uses this style. Some people prefer `8.27@tie{}in.'@: or +`8.27@tie{}inches'. In these cases, however, you need to use +@code{@@tie} (@pxref{@code{@@tie}}) or @code{@@w} (@pxref{@code{@@w}}) +so that no line break can occur between the number and the dimension. +Also, if you write a period after an abbreviation within a sentence +(as with the `in.'@: above), you should write @samp{@@:} after the +period to prevent @TeX{} from inserting extra whitespace, as shown +here. @xref{Not Ending a Sentence}. + + +@node Inserting Accents +@section Inserting Accents + +@cindex Inserting accents +@cindex Accents, inserting +@cindex Floating accents, inserting + +Here is a table with the commands Texinfo provides for inserting +floating accents. They all need an argument, the character to accent, +which can either be given in braces as usual (@code{@@'@{e@}}), or, as +a special case, the braces can be omitted, in which case the argument +is the next character (@code{@@'e}). This is to make the source as +convenient as possible to type and read, since accented characters are +very common in some languages. + +If the command is alphabetic, such as @code{@@dotaccent}, then there +must be a space between the command name and argument if braces are +not used. If the command is non-alphabetic, such as @code{@@'}, then +there must @emph{not} be a space; the argument is the very next +character. + +Exception: the argument to @code{@@tieaccent} must be enclosed in +braces (since it is two characters instead of one). + +To get the true accented characters output in Info, not just the ASCII +transliterations, it is necessary to specify @code{@@documentencoding} +with an encoding which supports the required characters +(@pxref{@code{@@documentencoding}}). In this case, you can also use +non-ASCII (e.g., pre-accented) characters in the source file. + +@findex " @r{(umlaut accent)} +@cindex Umlaut accent +@findex ' @r{(acute accent)} +@cindex Acute accent +@findex = @r{(macron accent)} +@cindex Macron accent +@findex ^ @r{(circumflex accent)} +@cindex Circumflex accent +@findex ` @r{(grave accent)} +@cindex Grave accent +@findex ~ @r{(tilde accent)} +@cindex Tilde accent +@findex , @r{(cedilla accent)} +@cindex Cedilla accent +@findex dotaccent +@cindex Dot accent +@findex H @r{(Hungarian umlaut accent)} +@cindex Hungarian umlaut accent +@findex ogonek +@cindex Ogonek diacritic +@findex ringaccent +@cindex Ring accent +@findex tieaccent +@cindex Tie-after accent +@findex u @r{(breve accent)} +@cindex Breve accent +@findex ubaraccent +@cindex Underbar accent +@findex udotaccent +@cindex Underdot accent +@findex v @r{(caron)} +@cindex Hacek accent +@cindex Check accent +@cindex Caron +@multitable {@t{@@questiondown@{@}}} {Output} {caron/hacek/check accent} +@headitem Command @tab Output @tab What +@item @t{@@"o} @tab @"o @tab umlaut accent +@item @t{@@'o} @tab @'o @tab acute accent +@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent +@item @t{@@=o} @tab @=o @tab macron/overbar accent +@item @t{@@^o} @tab @^o @tab circumflex accent +@item @t{@@`o} @tab @`o @tab grave accent +@item @t{@@~o} @tab @~o @tab tilde accent +@item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent +@item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut +@item @t{@@ogonek@{a@}} @tab @ogonek{a} @tab ogonek +@item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent +@item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent +@item @t{@@u@{o@}} @tab @u{o} @tab breve accent +@item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent +@item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent +@item @t{@@v@{o@}} @tab @v{o} @tab caron/hacek/check accent +@end multitable + +This table lists the Texinfo commands for inserting other characters +commonly used in languages other than English. + +@findex questiondown +@cindex @questiondown{} +@findex exclamdown +@cindex @exclamdown{} +@findex aa +@cindex @aa{} +@findex AA +@cindex @AA{} +@findex ae +@cindex @ae{} +@findex AE +@cindex @AE{} +@cindex Icelandic +@cindex Eth +@findex dh +@cindex @dh{} +@findex DH +@cindex @DH{} +@findex dotless +@cindex @dotless{i} (dotless i) +@cindex @dotless{j} (dotless j) +@cindex Dotless i, j +@findex l +@cindex @l{} +@findex L +@cindex @L{} +@findex o +@cindex @o{} +@findex O +@cindex @O{} +@findex oe +@cindex @oe{} +@findex OE +@cindex @OE{} +@cindex Romance ordinals +@cindex Ordinals, Romance +@cindex Feminine ordinal +@findex ordf +@cindex @ordf{} +@cindex Masculine ordinal +@findex ordm +@cindex @ordm{} +@findex ss +@cindex @ss{} +@cindex Es-zet +@cindex Sharp S +@cindex German S +@cindex Thorn +@findex th +@cindex @th{} +@findex TH +@cindex @TH{} +@multitable {@t{@@questiondown@{@}}} {oe OE} {es-zet or sharp S} +@item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! +@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? +@item @t{@@aa@{@} @@AA@{@}} @tab @aa{} @AA{} @tab a,A with circle +@item @t{@@ae@{@} @@AE@{@}} @tab @ae{} @AE{} @tab ae,AE ligatures +@item @t{@@dh@{@} @@DH@{@}} @tab @dh{} @DH{} @tab Icelandic eth +@item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i +@item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j +@item @t{@@l@{@} @@L@{@}} @tab @l{} @L{} @tab suppressed-L,l +@item @t{@@o@{@} @@O@{@}} @tab @o{} @O{} @tab O,o with slash +@item @t{@@oe@{@} @@OE@{@}} @tab @oe{} @OE{} @tab oe,OE ligatures +@item @t{@@ordf@{@} @@ordm@{@}} @tab @ordf{} @ordm{} @tab Spanish ordinals +@item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S +@item @t{@@th@{@} @@TH@{@}} @tab @th{} @TH{} @tab Icelandic thorn +@end multitable + + +@node Inserting Quotation Marks +@section Inserting Quotation Marks +@cindex Inserting quotation marks +@cindex Quotation marks, inserting + +@cindex Quotation characters (`'), in source +Use doubled single-quote characters to begin and end quotations: +@w{@t{`@w{}`@dots{}'@w{}'}}. @TeX{} converts two single quotes to +left- and right-hand doubled quotation marks, +@c this comes out as "like this" in Info, which is just confusing. +@iftex +``like this'', +@end iftex +and Info converts doubled single-quote characters to ASCII +double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}. + +You may occasionally need to produce two consecutive single quotes; +for example, in documenting a computer language such as Maxima where +@t{'@w{}'} is a valid command. You can do this with the input +@t{'@@w@{@}'}; the empty @code{@@w} command stops the combination into +the double-quote characters. + +@cindex Unicode quotation characters +@cindex Grave accent, vs. left quote +The left quote character (@t{`}, ASCII code 96) used in Texinfo is a +grave accent in ANSI and ISO character set standards. We use it as a +quote character because that is how @TeX{} is set up, by default. + +Texinfo supports several other quotation marks used in languages other +than English. Below is a table with the commands Texinfo provides for +inserting quotation marks. + +@cindex UTF-8 +@cindex ISO 8859-15 +@cindex Latin 9 +@cindex ISO 8859-1 +@cindex Latin 1 +In order to get the symbols for the quotation marks in encoded Info +output, it is necessary to specify @code{@@documentencoding UTF-8}. +(@xref{@code{@@documentencoding}}.) Double guillemets are also +present in ISO 8859-1 (aka Latin@tie{}1) and ISO 8859-15 (aka +Latin@tie{}9). + +@cindex European Computer Modern fonts +@cindex EC fonts +The standard @TeX{} fonts support the usual quotation marks used in +English (the ones produced with single and doubled ASCII +single-quotes). For the other quotation marks, @TeX{} uses European +Computer Modern (EC) fonts (@file{ecrm1000} and other variants). +These fonts are freely available, of course; you can download them +from @url{http://ctan.org/pkg/ec}, among other places. + +@cindex CM-Super fonts +The free EC fonts are bitmap fonts created with Metafont. Especially +for on-line viewing, Type@tie{}1 (vector) versions of the fonts are +preferable; these are available in the CM-Super font package +(@url{http://ctan.org/pkg/cm-super}). + +Both distributions include installation instructions. + +@cindex Single quotation marks +@cindex Double quotation marks +@cindex Left quotation marks +@cindex Right quotation marks +@findex quotedblleft +@cindex `@w{}` +@findex quoteleft +@cindex ` +@cindex " (undirected double quote character) +@findex quotedblright +@cindex '@w{}' +@findex quoteright +@cindex ' +@cindex Double low-9 quotation mark +@cindex Single low-9 quotation mark +@findex quotedblbase +@cindex @quotedblbase{} (double low-9 quotation mark) +@findex quotesinglbase +@cindex @quotesinglbase{} (single low-9 quotation mark) +@cindex Angle quotation marks +@cindex Guillemets +@cindex Guillemots +@cindex French quotation marks +@cindex Quotation marks, French +@cindex German quotation marks +@cindex Quotation marks, German +@cindex Double guillemets +@cindex Single guillemets +@cindex Double angle quotation marks +@cindex Single angle quotation marks +@cindex Left-pointing angle quotation marks +@cindex Right-pointing angle quotation marks +@cindex Double left-pointing angle quotation mark +@cindex Double right-pointing angle quotation mark +@cindex Single left-pointing angle quotation mark +@cindex Single right-pointing angle quotation mark +@findex guillemetleft +@findex guillemotleft +@cindex @sortas{<<} @guillemetleft{} +@findex guillemetright +@findex guillemotright +@cindex @guillemetright{} +@findex guilsinglleft +@cindex @sortas{<} @guilsinglleft{} +@findex guilsinglright +@cindex @guilsinglright{} +@c The third column doesn't have the full text in the prototype so that +@c the Info output fits within 72 columns. +@multitable {@t{@@quotedblright@{@} '@w{}'}} {Glyph} {Right-pointing double angle quotation} +@headitem Command @tab Glyph @tab Unicode name (point) +@item @verb{.@quotedblleft{} ``.} @tab @quotedblleft{} @tab Left double quotation mark (U+201C) +@item @verb{.@quotedblright{} ''.} @tab @quotedblright{} @tab Right double quotation mark (U+201D) +@item @verb{.@quoteleft{} `.} @tab @quoteleft{} @tab Left single quotation mark (U+2018) +@item @verb{.@quoteright{} '.} @tab @quoteright{} @tab Right single quotation mark (U+2019) +@item @t{@@quotedblbase@{@}} @tab @quotedblbase{} @tab Double low-9 quotation mark (U+201E) +@item @t{@@quotesinglbase@{@}} @tab @quotesinglbase{} @tab Single low-9 quotation mark (U+201A) +@item @t{@@guillemetleft@{@}} @tab @guillemetleft{} @tab Left-pointing double angle quotation mark (U+00AB) +@item @t{@@guillemetright@{@}} @tab @guillemetright{} @tab Right-pointing double angle quotation mark (U+00BB) +@item @t{@@guilsinglleft@{@}} @tab @guilsinglleft{} @tab Single left-pointing angle quotation mark (U+2039) +@item @t{@@guilsinglright@{@}} @tab @guilsinglright{} @tab Single right-pointing angle quotation mark (U+203A) +@end multitable + +@cindex Auk, bird species +For the double angle quotation marks, Adobe and @LaTeX{} glyph names +are also supported: @code{@@guillemotleft} and +@code{@@guillemotright}. These names are incorrect; a +``guillemot'' is a bird species (a type of auk). + +Traditions for quotation mark usage vary to a great extent between +languages (@url{http://en.wikipedia.org/wiki/Quotation_mark}). +Texinfo does not provide commands or configurations for typesetting +quotation marks according to the numerous traditions. Therefore, you +have to choose the commands appropriate for the language of your +manual. Sometimes aliases (@pxref{@code{@@alias}}) can simplify the +usage and make the source code more readable. For example, in German, +@code{@@quotedblbase} is used for the left double quote, and the right +double quote is the glyph produced by @code{@@quotedblleft}, which is +counter-intuitive. Thus, in this case the following aliases would be +convenient: + +@example +@@alias lgqq = quotedblbase +@@alias rgqq = quotedblleft +@end example + + +@node Inserting Subscripts and Superscripts +@section @code{@@sub} and @code{@@sup}: Inserting Subscripts and Superscripts + +@findex sub +@findex sup +@cindex Subscripts and superscripts, text + +You can insert subscripts and superscripts, in either text or math, +with the @code{@@sub} and @code{@@sup} commands. (For other +mathematical expressions, see the next section.) For example, here is +a purely textual subscript and superscript: + +@example +here@@sub@{below@}@@sup@{above@} +@end example + +@noindent produces: + +@display +here@sub{below}@sup{above} +@end display + +@cindex Math italic font +Inside @code{@@math}, @code{@@sub} and @code{@@sup} produce +mathematical subscripts and superscripts. This uses a different font +in the @TeX{} output (math italic instead of text italic); it makes no +difference in the other output formats. Here's an example: + +@example +@@math@{e@@sup@{x@}@} +@end example + +@noindent produces: + +@display +@math{e@sup{x}} +@end display + +In Info and plain text, regardless of being used inside @code{@@math}, +@code{@@sub@{@var{text}@}} is output as @samp{_@{@var{text}@}} and +@code{@@sup@{@var{text}@}} as @samp{^@{@var{text}@}}, including the +literal braces (to mark the beginning and end of the ``script'' text +to the reader). + +When the output format (and display program) permit (@TeX{} math, +HTML), the superscript is set above the subscript when both commands +are given consecutively. + + +@node Inserting Math +@section @code{@@math}: Inserting Mathematical Expressions + +@anchor{math}@c old name +@findex math +@cindex Mathematical expressions, inserting +@cindex Formulas, mathematical + +You can write a short mathematical expression with the @code{@@math} +command. Write the mathematical expression between braces, like this: + +@example +@@math@{(a + b) = (b + a)@} +@end example + +@iftex +@noindent This produces the following in @TeX{}: + +@display +@math{(a + b) = (b + a)} +@end display + +@noindent and the following in other formats: +@end iftex +@ifnottex +@noindent This produces the following in Info and HTML: +@end ifnottex + +@example +(a + b) = (b + a) +@end example + +@cindex MathML, not used +The @code{@@math} command has no special effect on the Info and HTML +output. @command{makeinfo} expands any @@-commands as usual, but it +does not try to use produce good mathematical formatting in any way +(no use of MathML, etc.). The HTML output is enclosed by +@code{<em>...</em>}, but nothing more. + +@findex \mathopsup +However, as far as the @TeX{} output is concerned, plain @TeX{} +mathematical commands are allowed in @code{@@math}, starting with +@samp{\}. In essence, @code{@@math} switches into plain @TeX{} math +mode. (Exception: the plain @TeX{} command @code{\sup}, which +typesets the mathematical operator name `sup', must be accessed as +@code{\mathopsup}, due to the conflict with Texinfo's @code{@@sup} +command.) + +This allows you to use all the plain @TeX{} math control sequences for +symbols, functions, and so on, and thus get proper formatting in the +@TeX{} output, at least. + +The @code{@@sub} and @code{@@sup} commands described in the previous +section produce subscripts and superscripts in HTML output as well as +@TeX{}; the plain @TeX{} characters @code{_} and @code{^} for +subscripts and superscripts are recognized by @TeX{} inside +@code{@@math}, but do nothing special in HTML or other output formats. + +It's best to use @samp{\} instead of @samp{@@} for any such +mathematical commands; otherwise, @command{makeinfo} will complain. +On the other hand, @command{makeinfo} does allow input with matching +(but unescaped) braces, such as @samp{k_@{75@}}; it complains about +such bare braces in regular input. + +Here's an example: + +@example +@@math@{\sin 2\pi \equiv \cos 3\pi@} +@end example + +@iftex +@noindent which looks like this in @TeX{}: +@display +@math{\sin 2\pi \equiv \cos 3\pi} +@end display + +@noindent but +@end iftex +@noindent which looks like the input in Info and HTML: +@example +\sin 2\pi \equiv \cos 3\pi +@end example + +@findex @sortas{\} \ @r{(literal \ in @code{@@math})} +Since @samp{\} is an escape character inside @code{@@math}, you can +use @code{@@\} to get a literal backslash (@code{\\} will work in +@TeX{}, but you'd get the literal two characters @samp{\\} in Info). +@code{@@\} is not defined outside of @code{@@math}, since a @samp{\} +ordinarily produces a literal (typewriter) @samp{\}. You can also use +@code{@@backslashchar@{@}} in any mode to get a typewriter backslash. +@xref{Inserting a Backslash}. + +@cindex Displayed equations +@cindex Equations, displayed +For displayed equations, you must at present use @TeX{} directly +(@pxref{Raw Formatter Commands}). + + +@node Glyphs for Text +@section Glyphs for Text + +@anchor{Glyphs}@c old name +@anchor{TeX and copyright}@c another old node, now split into two +@cindex Glyphs for text +@cindex Textual glyphs + +Texinfo has support for a few additional glyphs that are commonly used +in printed text but not available in ASCII@. Of course, there are +many thousands more. It is possible to use Unicode characters as-is +as far as @code{makeinfo} is concerned, but @TeX{} is not so lucky. + +@menu +* @code{@@TeX @@LaTeX}:: The @TeX{} logos. +* @code{@@copyright}:: The copyright symbol (c in a circle). +* @code{@@registeredsymbol}:: The registered symbol (R in a circle). +* @code{@@dots}:: How to insert ellipses: @dots{} and @enddots{} +* @code{@@bullet}:: How to insert a bullet: @bullet{} +* @code{@@euro}:: How to insert the euro currency symbol. +* @code{@@pounds}:: How to insert the pounds currency symbol. +* @code{@@textdegree}:: How to insert the degrees symbol. +* @code{@@minus}:: How to insert a minus sign. +* @code{@@geq @@leq}:: How to insert greater/less-than-or-equal signs. +@end menu + + +@node @code{@@TeX @@LaTeX} +@subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{}) + +@anchor{tex}@c old name +@findex TeX +@findex LaTeX +@cindex Logos, @TeX{} +@cindex @TeX{} logo +@cindex @LaTeX{} logo + +Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed +manual, this is a special logo that is different from three ordinary +letters. In Info, it just looks like @samp{TeX}. + +Similarly, use the @code{@@LaTeX@{@}} command to generate `@LaTeX{}', +which is even more special in printed manuals (and different from the +incorrect @code{La@@TeX@{@}}. In Info, the result is just +@samp{LaTeX}. (@LaTeX{} is another macro package built on top of +@TeX{}, very loosely analogous to Texinfo in that it emphasizes +logical structure, but much (much) larger.) + +The spelling of these commands are unusual for Texinfo, in that they +use both uppercase and lowercase letters. + + +@node @code{@@copyright} +@subsection @code{@@copyright@{@}} (@copyright{}) + +@anchor{copyright symbol}@c old name +@findex copyright +@cindex Copyright symbol + +Use the @code{@@copyright@{@}} command to generate the copyright +symbol, `@copyright{}'. Where possible, this is a @samp{c} inside a +circle; in Info, this is @samp{(C)}. + +Legally, it's not necessary to use the copyright symbol; the English +word `Copyright' suffices, according to international treaty. + + +@node @code{@@registeredsymbol} +@subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{}) + +@anchor{registered symbol}@c old name +@findex registeredsymbol +@cindex Registered symbol + +Use the @code{@@registeredsymbol@{@}} command to generate the +registered symbol, `@registeredsymbol{}'. Where possible, this is an +@samp{R} inside a circle; in Info, this is @samp{(R)}. + + +@node @code{@@dots} +@subsection @code{@@dots} (@dots{}) and @code{@@enddots} (@enddots{}) + +@anchor{dots}@c old name +@findex dots +@findex enddots +@cindex Inserting dots +@cindex Inserting ellipsis +@cindex Dots, inserting +@cindex Ellipsis, inserting + +@anchor{Dots Bullets}@c old name + +An @dfn{ellipsis} (a sequence of dots) would be spaced wrong when +typeset as a string of periods, so a special command is used in +Texinfo: use the @code{@@dots@{@}} command to generate a normal +ellipsis, which is three dots in a row, appropriately spaced @dots{} +like so. To emphasize: do not simply write three periods in the input +file; that would work for the Info file output, but would produce the +wrong amount of space between the periods in the printed manual. + +The @code{@@enddots@{@}} command generates an end-of-sentence +ellipsis, which also has three dots, but with different spacing +afterwards, @enddots{} Look closely to see the difference. + +Here is an ellipsis: @dots{} +Here are three periods in a row: ... + +In printed (and usually HTML) output, the three periods in a row are +much closer together than the dots in the ellipsis. + + +@node @code{@@bullet} +@subsection @code{@@bullet} (@bullet{}) + +@anchor{bullet}@c old name +@findex bullet + +Use the @code{@@bullet@{@}} command to generate a large round dot, or +the closest possible thing to one. In Info, an asterisk is used. +Here is a bullet: @bullet{} + +When you use @code{@@bullet} in @code{@@itemize}, you do not need to +type the braces, because @code{@@itemize} supplies them. +(@pxref{@code{@@itemize}}). + + +@node @code{@@euro} +@subsection @code{@@euro} (@euro{}): Euro Currency Symbol + +@anchor{euro}@c old name +@findex euro +@cindex Euro symbol, producing + +Use the @code{@@euro@{@}} command to generate `@euro{}'. Where +possible, this is the symbol for the Euro currency. Otherwise, the +word @samp{Euro} is used. + +Texinfo cannot magically synthesize support for the Euro symbol where +the underlying system (fonts, software, whatever) does not support it. +Therefore, you may find it preferable to use the word ``Euro''. (In +banking contexts, the abbreviation for the Euro is EUR@.) + +@cindex ISO 8859-15, and Euro +@cindex Latin 9, and Euro +In order to get the Euro symbol in encoded Info output, for example, +it is necessary to specify @code{@@documentencoding ISO-8859-15} or +@code{@@documentencoding UTF-8} (@xref{@code{@@documentencoding}}.) +The Euro symbol is in ISO 8859-15 (aka Latin@tie{}9), and is +@emph{not} in the more widely-used ISO 8859-1 (Latin@tie{}1). + +@pindex feymr10 +@cindex Euro font +The Euro symbol does not exist in the standard @TeX{} fonts (which +were designed before the Euro was legislated into existence). +Therefore, @TeX{} uses an additional font, named @code{feymr10} (along +with other variables). It is freely available, of course; you can +download it from @url{http://ctan.org/pkg/eurosym}, among other +places. The distribution includes installation instructions. + + +@node @code{@@pounds} +@subsection @code{@@pounds} (@pounds{}): Pounds Sterling + +@anchor{pounds}@c old name +@findex pounds +@cindex Pounds symbol + +Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where +possible, this is the symbol for the pounds sterling British currency. +Otherwise, it is @samp{#}. + + +@node @code{@@textdegree} +@subsection @code{@@textdegree} (@textdegree{}): Degrees Symbol + +@anchor{textdegree}@c old name +@findex textdegree +@cindex Degree symbol + +Use the @code{@@textdegree@{@}} command to generate `@textdegree{}'. +Where possible, this is the normal symbol for degrees. Otherwise, +it is an @samp{o}. + + +@node @code{@@minus} +@subsection @code{@@minus} (@minus{}): Inserting a Minus Sign + +@anchor{minus}@c old name +@findex minus +@cindex Minus sign + +@cindex Em dash, compared to minus sign +@cindex Hyphen, compared to minus +Use the @code{@@minus@{@}} command to generate a minus sign. In a +fixed-width font, this is a single hyphen, but in a proportional font, +the symbol is the customary length for a minus sign---a little longer +than a hyphen, shorter than an em-dash: + +@display +@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}}, + +`-' is a hyphen generated with the character @samp{-}, + +`---' is an em-dash for text. +@end display + +@noindent +In the fixed-width font used by Info, @code{@@minus@{@}} is the same +as a hyphen. + +You should not use @code{@@minus@{@}} inside @code{@@code} or +@code{@@example} because the width distinction is not made in the +fixed-width font they use. + +When you use @code{@@minus} to specify the mark beginning each entry +in an itemized list, you do not need to type the braces +(@pxref{@code{@@itemize}}). + +If you actually want to typeset some math that does a subtraction, it +is better to use @code{@@math}. Then the regular @samp{-} character +produces a minus sign, as in @code{@@math@{a-b@}} (@pxref{Inserting +Math}). + + +@node @code{@@geq @@leq} +@subsection @code{@@geq} (@geq{}) and @code{@@leq} (@leq{}): Inserting Relations + +@anchor{geq leq}@c old name +@findex geq +@findex leq + +Use the @code{@@geq@{@}} and @code{@@leq@{@}} commands to generate +greater-than-or-equal and less-than-equal-signs, `@geq{}' and +`@leq{}'. When those symbols are not available, the ASCII sequences +@samp{>=} and @samp{<=} are output. + + +@node Glyphs for Programming +@section Glyphs for Programming + +@cindex Glyphs for programming +@cindex Examples, glyphs for +@cindex Programming, glyphs for + +In Texinfo, code is often illustrated in examples that are delimited +by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and +@code{@@end lisp}. In such examples, you can indicate the results of +evaluation or an expansion using @samp{@result{}} or +@samp{@expansion{}}. Likewise, there are commands to insert glyphs to +indicate printed output, error messages, equivalence of expressions, +the location of point in an editor, and GUI operation sequences. + +The glyph-insertion commands do not need to be used within an example, +but most often they are. All glyph-insertion commands are followed by +empty braces. + +@menu +* Glyphs Summary:: +* @code{@@result}:: How to show the result of expression. +* @code{@@expansion}:: How to indicate an expansion. +* @code{@@print}:: How to indicate generated output. +* @code{@@error}:: How to indicate an error message. +* @code{@@equiv}:: How to indicate equivalence. +* @code{@@point}:: How to indicate the location of point. +* Click Sequences:: Inserting GUI usage sequences. +@end menu + + +@node Glyphs Summary +@subsection Glyphs Summary + +Here is a summary of the glyph commands: + +@table @asis +@item @result{} +@code{@@result@{@}} indicates the result of an expression. + +@item @expansion{} +@code{@@expansion@{@}} indicates the results of a macro expansion. + +@item @print{} +@code{@@print@{@}} indicates printed output. + +@item @error{} +@code{@@error@{@}} indicates the following text is an error message. + +@item @equiv{} +@code{@@equiv@{@}} indicates the exact equivalence of two forms. + +@item @point{} +@code{@@point@{@}} shows the location of point. + +@item @clicksequence{A @click{} B} +@code{@@clicksequence@{A @@click@{@} B} indicates a GUI operation +sequence: first A, then clicking B, or choosing B from a menu, or +otherwise selecting it. +@end table + + +@node @code{@@result} +@subsection @code{@@result@{@}} (@result{}): Result of an Expression + +@anchor{result}@c old name +@findex result +@cindex Result of an expression +@cindex Indicating evaluation +@cindex Evaluation glyph +@cindex Value of an expression, indicating + +Use the @code{@@result@{@}} command to indicate the result of +evaluating an expression. + +The @code{@@result@{@}} command is displayed as @samp{@result{}}, +either a double stemmed arrow or (when that is not available) the +ASCII sequence @samp{=>}. + +Thus, the following, + +@lisp +(cdr '(1 2 3)) + @result{} (2 3) +@end lisp + +@noindent +may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. + + +@node @code{@@expansion} +@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion + +@anchor{expansion}@c old name +@cindex Expansion, indicating +@cindex Macro expansion, indicating +@findex expansion + +When an expression is a macro call, it expands into a new expression. +You can indicate the result of the expansion with the +@code{@@expansion@{@}} command. + +The @code{@@expansion@{@}} command is displayed as +@samp{@expansion{}}, either a long arrow with a flat base or (when +that is not available) the ASCII sequence @samp{==>}. + +@need 700 +For example, the following + +@example +@group +@@lisp +(third '(a b c)) + @@expansion@{@} (car (cdr (cdr '(a b c)))) + @@result@{@} c +@@end lisp +@end group +@end example + +@noindent +produces + +@lisp +@group +(third '(a b c)) + @expansion{} (car (cdr (cdr '(a b c)))) + @result{} c +@end group +@end lisp + +@noindent +which may be read as: + +@quotation +@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))}; +the result of evaluating the expression is @code{c}. +@end quotation + +@noindent +Often, as in this case, an example looks better if the +@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented. + + +@node @code{@@print} +@subsection @code{@@print@{@}} (@print{}): Indicating Generated Output + +@anchor{Print Glyph}@c old name +@findex print +@cindex Printed output, indicating + +Sometimes an expression will generate output during its execution. +You can indicate such displayed output with the @code{@@print@{@}} +command. + +The @code{@@print@{@}} command is displayed as @samp{@print{}}, either +a horizontal dash butting against a vertical bar or (when that is not +available) the ASCII sequence @samp{-|}. + +In the following example, the printed text is indicated with +@samp{@print{}}, and the value of the expression follows on the +last line. + +@lisp +@group +(progn (print 'foo) (print 'bar)) + @print{} foo + @print{} bar + @result{} bar +@end group +@end lisp + +@noindent +In a Texinfo source file, this example is written as follows: + +@lisp +@group +@@lisp +(progn (print 'foo) (print 'bar)) + @@print@{@} foo + @@print@{@} bar + @@result@{@} bar +@@end lisp +@end group +@end lisp + + +@node @code{@@error} +@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message + +@anchor{Error Glyph}@c old name +@cindex Error message, indicating +@findex error + +A piece of code may cause an error when you evaluate it. You can +designate the error message with the @code{@@error@{@}} command. + +The @code{@@error@{@}} command is displayed as @samp{@error{}}, either +the word `error' in a box in the printed output, the word error +followed by an arrow in other formats or (when no arrow is available) +@samp{error-->}. + +@need 700 +Thus, + +@example +@@lisp +(+ 23 'x) +@@error@{@} Wrong type argument: integer-or-marker-p, x +@@end lisp +@end example + +@noindent +produces + +@lisp +(+ 23 'x) +@error{} Wrong type argument: integer-or-marker-p, x +@end lisp + +@noindent +This indicates that the following error message is printed +when you evaluate the expression: + +@lisp +Wrong type argument: integer-or-marker-p, x +@end lisp + +The word @samp{@error{}} itself is not part of the error message. + + +@node @code{@@equiv} +@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence + +@anchor{Equivalence}@c oldname +@cindex Equivalence, indicating +@findex equiv + +Sometimes two expressions produce identical results. You can indicate +the exact equivalence of two forms with the @code{@@equiv@{@}} +command. The @code{@@equiv@{@}} command is displayed as +@samp{@equiv{}}, either a standard mathematical equivalence sign +(three parallel horizontal lines) or (when that is not available) as +the ASCII sequence @samp{==}. + +Thus, + +@example +@@lisp +(make-sparse-keymap) @@equiv@{@} (list 'keymap) +@@end lisp +@end example + +@noindent +produces + +@lisp +(make-sparse-keymap) @equiv{} (list 'keymap) +@end lisp + +@noindent +This indicates that evaluating @code{(make-sparse-keymap)} produces +identical results to evaluating @code{(list 'keymap)}. + + +@node @code{@@point} +@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer + +@anchor{Point Glyph}@c old name +@cindex Point, indicating in a buffer +@findex point + +Sometimes you need to show an example of text in an Emacs buffer. In +such examples, the convention is to include the entire contents of the +buffer in question between two lines of dashes containing the buffer +name. + +You can use the @samp{@@point@{@}} command to show the location of +point in the text in the buffer. (The symbol for point, of course, is +not part of the text in the buffer; it indicates the place +@emph{between} two characters where point is located.) + +The @code{@@point@{@}} command is displayed as @samp{@point{}}, either +a pointed star or (when that is not available) the ASCII sequence +@samp{-!-}. + +The following example shows the contents of buffer @file{foo} before +and after evaluating a Lisp command to insert the word @code{changed}. + +@example +@group +---------- Buffer: foo ---------- +This is the @point{}contents of foo. +---------- Buffer: foo ---------- + +@end group +@end example + +@example +@group +(insert "changed ") + @result{} nil +---------- Buffer: foo ---------- +This is the changed @point{}contents of foo. +---------- Buffer: foo ---------- + +@end group +@end example + +In a Texinfo source file, the example is written like this: + +@example +@@example +---------- Buffer: foo ---------- +This is the @@point@{@}contents of foo. +---------- Buffer: foo ---------- + +(insert "changed ") + @@result@{@} nil +---------- Buffer: foo ---------- +This is the changed @@point@{@}contents of foo. +---------- Buffer: foo ---------- +@@end example +@end example + + +@node Click Sequences +@subsection Click Sequences + +@cindex Click sequences +@cindex Sequence of clicks +@cindex GUI click sequence + +@findex clicksequence +When documenting graphical interfaces, it is necessary to describe +sequences such as `Click on @samp{File}, then choose @samp{Open}, then +@dots{}'. Texinfo offers commands @code{@@clicksequence} and +@code{click} to represent this, typically used like this: + +@example +@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{} +@end example + +@noindent +which produces: + +@display +@dots{} @clicksequence{File @click{} Open} @dots{} +@end display + +@findex click +@findex arrow +The @code{@@click} command produces a right arrow by default; this +glyph is also available independently via the command +@code{@@arrow@{@}}. + +@findex clickstyle +You can change the glyph produced by @code{@@click} with the command +@code{@@clickstyle}, which takes a command name as its single argument +on the rest of the line, much like @code{@@itemize} and friends +(@pxref{@code{@@itemize}}). The command should produce a glyph, and +the usual empty braces @samp{@{@}} are omitted. Here's an example: + +@example +@@clickstyle @@result +@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{} +@end example + +@noindent +now produces: + +@display +@clickstyle @result +@dots{} @clicksequence{File @click{} Open} @dots{} +@end display + + +@node Inserting Unicode +@section Inserting Unicode: @code{@@U} + +@cindex Unicode character, inserting +@cindex Code point of Unicode character, inserting by +@findex U + +The command @code{@@U@{@var{hex}@}} inserts a representation of the +Unicode character U+@var{hex}. For example, @code{@@U@{0132@}} +inserts the Dutch `IJ' ligature (poorly shown here as simply the two +letters `I' and `J'). + +The @var{hex} value should be at least four hex digits; leading zeros +are @emph{not} added. In general, @var{hex} must specify a valid +normal Unicode character; e.g., U+10FFFF (the very last code point) is +invalid by definition, and thus cannot be inserted this way. + +@cindex ASCII, source document portability using +@code{@@U} is useful for inserting occasional glyphs for which Texinfo +has no dedicated command, while allowing the Texinfo source to remain +purely 7-bit ASCII for maximum portability. + +@cindex Unicode and @TeX{} +This command has many limitations---the same limitations as inserting +Unicode characters in UTF-8 or another binary form. First and most +importantly, @TeX{} knows nothing about most of Unicode. Supporting +specific additional glyphs upon request is possible, but it's not +viable for @file{texinfo.tex} to support whole additional scripts +(Japanese, Urdu, @dots{}). The @code{@@U} command does nothing to +change this. If the specified character is not supported in @TeX{}, +an error is given. (@xref{@code{@@documentencoding}}.) + +@cindex Entity reference in HTML et al. +@cindex @samp{&#x@var{hex};}, output from @code{@@U} +In HTML, XML, and Docbook, the output from @code{@@U} is always an +entity reference of the form @samp{&#x@var{hex};}, as in +@samp{IJ} for the example above. This should work even when an +HTML document uses some other encoding (say, Latin@tie{}1) and the +given character is not supported in that encoding. + +@cindex UTF-8, output from @code{@@U} +In Info and plain text, if the document encoding is specified +explicitly to be UTF-8, the output will be the UTF-8 representation of +the character U+@var{hex} (presuming it's a valid character). In all +other cases, the output is the ASCII sequence @samp{U+@var{hex}}, as +in the six ASCII characters @samp{U+0132} for the example above. + +That's all. No magic! + + +@node Breaks +@chapter Forcing and Preventing Breaks + +@cindex Forcing line and page breaks +@cindex Making line and page breaks +@cindex Preventing line and page breaks +@cindex Line breaks, awkward +@cindex Page breaks, awkward + +Line and page breaks can sometimes occur in the `wrong' place in one +or another form of output. It's up to you to ensure that text looks +right in all the output formats. + +For example, in a printed manual, page breaks may occur awkwardly in +the middle of an example; to prevent this, you can hold text together +using a grouping command that keeps the text from being split across +two pages. Conversely, you may want to force a page break where none +would occur normally. + +You can use the break, break prevention, or pagination commands to fix +problematic line and page breaks. + +@menu +* Break Commands:: Summary of break-related commands. +* Line Breaks:: Forcing line breaks. +* @code{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points. +* @code{@@allowcodebreaks}:: Controlling line breaks within @@code text. +* @code{@@w}:: Preventing unwanted line breaks in text. +* @code{@@tie}:: Inserting an unbreakable but varying space. +* @code{@@sp}:: Inserting blank lines. +* @code{@@page}:: Forcing the start of a new page. +* @code{@@group}:: Preventing unwanted page breaks. +* @code{@@need}:: Another way to prevent unwanted page breaks. +@end menu + + +@node Break Commands +@section Break Commands + +The break commands create or allow line and paragraph breaks: + +@table @code +@item @@* +Force a line break. + +@item @@sp @var{n} +Skip @var{n} blank lines. + +@item @@- +Insert a discretionary hyphen. + +@item @@hyphenation@{@var{hy-phen-a-ted words}@} +Define hyphen points in @var{hy-phen-a-ted words}. +@end table + +These commands hold text together on a single line: + +@table @code +@item @@w@{@var{text}@} +Prevent @var{text} from being split and hyphenated across two lines. + +@item @@tie@{@} +Insert a normal interword space at which a line break may not occur. +@end table + +The pagination commands apply only to printed output, since other +output formats do not have pages. + +@table @code +@item @@page +Start a new page. + +@item @@group +Hold text together that must appear on one page. + +@item @@need @var{mils} +Start a new page if not enough space on this one. +@end table + + +@node Line Breaks +@section @code{@@*} and @code{@@/}: Generate and Allow Line Breaks + +@findex * @r{(force line break)} +@findex / @r{(allow line break)} +@cindex Line breaks, controlling +@cindex Controlling line breaks +@cindex Breaks in a line +@cindex Force line break +@cindex Allow line break + +The @code{@@*} command forces a line break in all output formats. +The @code{@@/} command allows a line break (printed manual only). + +Here is an example with @code{@@*}: + +@example +This sentence is broken @@*into two lines. +@end example + +@noindent produces + +@example +@group +This sentence is broken +into two lines. +@end group +@end example + +The @code{@@/} command can be useful within long urls or other +identifiers where @TeX{} can't find a good place to break. @TeX{} +will automatically break urls at the natural places (@pxref{URL Line +Breaking}), so only use @code{@@/} if you need it. @code{@@/} has no +effect in the other output format. + + +@node @code{@@- @@hyphenation} +@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate + +@anchor{- and hyphenation}@c old name +@findex @sortas{-} - @r{(discretionary hyphen)} +@findex hyphenation +@cindex Hyphenation, helping @TeX{} do +@cindex Fine-tuning, and hyphenation + +Although @TeX{}'s hyphenation algorithm is generally pretty good, it +does miss useful hyphenation points from time to time. (Or, far more +rarely, insert an incorrect hyphenation.) So, for documents with an +unusual vocabulary or when fine-tuning for a printed edition, you may +wish to help @TeX{} out. Texinfo supports two commands for this: + +@table @code +@item @@- +Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does +not have to) hyphenate. This is especially useful when you notice an +overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull +hboxes}). @TeX{} will not insert any hyphenation points itself into a +word containing @code{@@-}. + +@item @@hyphenation@{@var{hy-phen-a-ted words}@} +Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you +put a @samp{-} at each hyphenation point. For example: +@example +@@hyphenation@{man-u-script man-u-scripts@} +@end example +@noindent @TeX{} only uses the specified hyphenation points when the +words match exactly, so give all necessary variants, such as plurals. +@end table + +Info, HTML, and other non-@TeX{} output is not hyphenated, so none of +these commands have any effect there. + + +@node @code{@@allowcodebreaks} +@section @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code} + +@anchor{allowcodebreaks}@c old name +@findex allowcodebreaks +@cindex Breaks, within @code{@@code} +@cindex @sortas{-} -, breakpoint within @code{@@code} +@cindex Hyphen, breakpoint within @code{@@code} +@cindex Dash, breakpoint within @code{@@code} +@cindex _, breakpoint within @code{@@code} +@cindex Underscore, breakpoint within @code{@@code} + +Ordinarily, @TeX{} considers breaking lines at @samp{-} and @samp{_} +characters within @code{@@code} and related commands +(@pxref{@code{@@code}}), more or less as if they were ``empty'' +hyphenation points. + +This is necessary since many manuals, especially for Lisp-family +languages, must document very long identifiers. On the other hand, +some manuals don't have this problems, and you may not wish to allow a +line break at the underscore in, for example, @code{SIZE_MAX}, or even +worse, after any of the four underscores in @code{__typeof__}. + +So Texinfo provides this command: + +@example +@@allowcodebreaks false +@end example + +@noindent to prevent from breaking at @samp{-} or @samp{_} within +@code{@@code}. You can go back to allowing such breaks with +@code{@@allowcodebreaks true}. Write these commands on lines by +themselves. + +These commands can be given anywhere in the document. For example, +you may have just one problematic paragraph where you need to turn off +the breaks, but want them in general, or vice versa. + +This command has no effect except in HTML and @TeX{} output. + + +@node @code{@@w} +@section @code{@@w}@{@var{text}@}: Prevent Line Breaks + +@anchor{w}@c old name +@findex w +@cindex Line breaks, preventing + +@code{@@w@{@var{text}@}} outputs @var{text}, while prohibiting line +breaks within @var{text}. + +@cindex Non-breakable space, fixed +@cindex Unbreakable space, fixed +Thus, you can use @code{@@w} to produce a non-breakable space, fixed at +the width of a normal interword space: + +@example +@@w@{ @} @@w@{ @} @@w@{ @} indentation. +@end example + +@noindent produces: + +@display +@w{ } @w{ } @w{ } indentation. +@end display + +The space from @code{@@w@{@w{ }@}}, as well as being non-breakable, +also will not stretch or shrink. Sometimes that is what you want, for +instance if you're doing manual indenting. However, usually you want +a normal interword space that does stretch and shrink (in the printed +output); for that, see the @code{@@tie} command in the next section. + +@cindex Hyphenation, preventing +You can also use the @code{@@w} command to prevent @TeX{} from +automatically hyphenating a long name or phrase that happens to fall +near the end of a line. @command{makeinfo} does not ever hyphenate +words. + +@cindex Keyword expansion, preventing +@cindex Version control keywords, preventing expansion of +@cindex $Id expansion, preventing +You can also use @code{@@w} to avoid unwanted keyword expansion in +source control systems. For example, to literally write @t{@w{$}Id$} +in your document, use @code{@@w@{$@}Id$}. This trick isn't effective +in Info or plain text output, though. + + +@node @code{@@tie} +@section @code{@@tie@{@}}: Inserting an Unbreakable Space + +@anchor{tie}@c old name +@findex tie @r{(unbreakable interword space)} +@cindex Tied space +@cindex Non-breakable space, variable +@cindex Unbreakable space, variable + +The @code{@@tie@{@}} command produces a normal interword space at which +a line break may not occur. Always write it with following (empty) +braces, as usual for commands used within a paragraph. Here's an +example: + +@example +@@TeX@{@} was written by Donald E.@@tie@{@}Knuth. +@end example + +@noindent produces: + +@display +@TeX{} was written by Donald E.@tie{}Knuth. +@end display + +There are two important differences between @code{@@tie@{@}} and +@code{@@w@{@w{ }@}}: + +@itemize +@item +The space produced by @code{@@tie@{@}} will stretch and shrink slightly +along with the normal interword spaces in the paragraph; the space +produced by @code{@@w@{@w{ }@}} will not vary. + +@item +@code{@@tie@{@}} allows hyphenation of the surrounding words, while +@code{@@w@{@w{ }@}} inhibits hyphenation of those words (for @TeX{}nical +reasons, namely that it produces an @samp{\hbox}). + +@end itemize + + +@node @code{@@sp} +@section @code{@@sp} @var{n}: Insert Blank Lines + +@anchor{sp}@c old name +@findex sp @r{(line spacing)} +@cindex Space, inserting vertical +@cindex Blank lines +@cindex Line spacing + +A line beginning with and containing only @code{@@sp @var{n}} +generates @var{n} blank lines of space in both the printed manual and +the Info file. @code{@@sp} also forces a paragraph break. For +example, + +@example +@@sp 2 +@end example + +@noindent +generates two blank lines. + +The @code{@@sp} command is most often used in the title page. + + +@node @code{@@page} +@section @code{@@page}: Start a New Page + +@anchor{page}@c old name +@findex page +@cindex Page breaks, forcing + +A line containing only @code{@@page} starts a new page in a printed +manual. In other formats, without the concept of pages, it starts a +new paragraph. A @code{@@page} command is often used in the +@code{@@titlepage} section of a Texinfo file to start the copyright +page. + + +@node @code{@@group} +@section @code{@@group}: Prevent Page Breaks + +@anchor{group}@c old name +@findex group +@cindex Group (hold text together vertically) +@cindex Holding text together vertically +@cindex Vertically holding text together + +The @code{@@group} command (on a line by itself) is used inside an +@code{@@example} or similar construct to begin an unsplittable vertical +group, which will appear entirely on one page in the printed output. +The group is terminated by a line containing only @code{@@end group}. +These two lines produce no output of their own, and in the Info file +output they have no effect at all. + +@c Once said that these environments +@c turn off vertical spacing between ``paragraphs''. +@c Also, quotation used to work, but doesn't in texinfo-2.72 +Although @code{@@group} would make sense conceptually in a wide +variety of contexts, its current implementation works reliably only +within @code{@@example} and variants, and within @code{@@display}, +@code{@@format}, @code{@@flushleft} and @code{@@flushright}. +@xref{Quotations and Examples}. (What all these commands have in +common is that each line of input produces a line of output.) In +other contexts, @code{@@group} can cause anomalous vertical +spacing. + +@need 750 +This formatting requirement means that you should write: + +@example +@group +@@example +@@group +@dots{} +@@end group +@@end example +@end group +@end example + +@noindent +with the @code{@@group} and @code{@@end group} commands inside the +@code{@@example} and @code{@@end example} commands. + +The @code{@@group} command is most often used to hold an example +together on one page. In this Texinfo manual, more than 100 examples +contain text that is enclosed between @code{@@group} and @code{@@end +group}. + +If you forget to end a group, you may get strange and unfathomable +error messages when you run @TeX{}. This is because @TeX{} keeps +trying to put the rest of the Texinfo file onto the one page and does +not start to generate error messages until it has processed +considerable text. It is a good rule of thumb to look for a missing +@code{@@end group} if you get incomprehensible error messages in +@TeX{}. + + +@node @code{@@need} +@section @code{@@need @var{mils}}: Prevent Page Breaks + +@anchor{need}@c old name +@findex need +@cindex Need space at page bottom +@cindex Mils, argument to @code{@@need} + +A line containing only @code{@@need @var{n}} starts a new page in a +printed manual if fewer than @var{n} mils (thousandths of an inch) +remain on the current page. Do not use braces around the argument +@var{n}. The @code{@@need} command has no effect on other output +formats since they are not paginated. + +@need 800 +This paragraph is preceded by a @code{@@need} command that tells +@TeX{} to start a new page if fewer than 800 mils (eight-tenths +inch) remain on the page. It looks like this: + +@example +@group +@@need 800 +This paragraph is preceded by @dots{} +@end group +@end example + +@cindex Orphans, preventing +The @code{@@need} command is useful for preventing orphans: single +lines at the bottoms of printed pages. + + +@node Definition Commands +@chapter Definition Commands +@cindex Definition commands + +The @code{@@deffn} command and the other @dfn{definition commands} +enable you to describe functions, variables, macros, commands, user +options, special forms and other such artifacts in a uniform +format. + +In the Info file, a definition causes the entity +category---`Function', `Variable', or whatever---to appear at the +beginning of the first line of the definition, followed by the +entity's name and arguments. In the printed manual, the command +causes @TeX{} to print the entity's name and its arguments on the left +margin and print the category next to the right margin. In both +output formats, the body of the definition is indented. Also, the +name of the entity is entered into the appropriate index: +@code{@@deffn} enters the name into the index of functions, +@code{@@defvr} enters it into the index of variables, and so +on (@pxref{Predefined Indices}). + +A manual need not and should not contain more than one definition for +a given name. An appendix containing a summary should use +@code{@@table} rather than the definition commands. + +@menu +* Def Cmd Template:: Writing descriptions using definition commands. +* Def Cmd Continuation Lines:: Continuing the heading over source lines. +* Optional Arguments:: Handling optional and repeated arguments. +* @code{@@deffnx}:: Group two or more `first' lines. +* Def Cmds in Detail:: Reference for all the definition commands. +* Def Cmd Conventions:: Conventions for writing definitions. +* Sample Function Definition:: An example. +@end menu + + +@node Def Cmd Template +@section The Template for a Definition +@cindex Definition template +@cindex Template for a definition + +The @code{@@deffn} command is used for definitions of entities that +resemble functions. To write a definition using the @code{@@deffn} +command, write the @code{@@deffn} command at the beginning of a line +and follow it on the same line by the category of the entity, the name +of the entity itself, and its arguments (if any). Then write the body +of the definition on succeeding lines. (You may embed examples in the +body.) Finally, end the definition with an @code{@@end deffn} command +written on a line of its own. + +The other definition commands follow the same format: a line with the +@code{@@def@dots{}} command and whatever arguments are appropriate for +that command; the body of the definition; and a corresponding +@code{@@end} line. + +The template for a definition looks like this: + +@example +@group +@@deffn @var{category} @var{name} @var{arguments}@dots{} +@var{body-of-definition} +@@end deffn +@end group +@end example + +@need 700 +@noindent +For example, + +@example +@group +@@deffn Command forward-word count +This command moves point forward @@var@{count@} words +(or backward if @@var@{count@} is negative). @dots{} +@@end deffn +@end group +@end example + +@noindent +produces + +@quotation +@deffn Command forward-word count +This command moves point forward @var{count} words +(or backward if @var{count} is negative). @dots{} +@end deffn +@end quotation + +Capitalize the category name like a title. If the name of the +category contains spaces, as in the phrase `Interactive Command', +enclose it in braces. For example: + +@example +@group +@@deffn @{Interactive Command@} isearch-forward +@dots{} +@@end deffn +@end group +@end example + +@noindent +Otherwise, the second word will be mistaken for the name of the +entity. As a general rule, when any of the arguments in the heading +line @emph{except} the last one are more than one word, you need to +enclose them in braces. This may also be necessary if the text +contains commands, for example, @samp{@{declaraci@@'on@}} if you are +writing in Spanish. + +Some of the definition commands are more general than others. The +@code{@@deffn} command, for example, is the general definition command +for functions and the like---for entities that may take arguments. +When you use this command, you specify the category to which the +entity belongs. Three predefined, specialized variations +(@code{@@defun}, @code{@@defmac}, and @code{@@defspec}) specify the +category for you: ``Function'', ``Macro'', and ``Special Form'' +respectively. (In Lisp, a special form is an entity much like a +function.) Similarly, the general @code{@@defvr} command is +accompanied by several specialized variations for describing +particular kinds of variables. + +@xref{Sample Function Definition}, for a detailed example of a +function definition, including the use of @code{@@example} inside the +definition. + + +@node Def Cmd Continuation Lines +@section Definition Command Continuation Lines +@cindex Continuation lines in definition commands +@cindex Definition command headings, continuing +@cindex @sortas{@@} @samp{@@} as continuation in definition commands + +The heading line of a definition command can get very long. +Therefore, Texinfo has a special syntax allowing them to be continued +over multiple lines of the source file: a lone @samp{@@} at the end of +each line to be continued. Here's an example: + +@example +@@defun fn-name @@ + arg1 arg2 arg3 +This is the basic continued defun. +@@end defun +@end example + +@noindent produces: + +@defun fn-name arg1 arg2 arg3 +This is the basic continued defun. +@end defun + +@noindent +As you can see, the continued lines are combined, as if they had been +typed on one source line. + +Although this example only shows a one-line continuation, +continuations may extend over any number of lines, in the same way; +put an @code{@@} at the end of each line to be continued. + +@cindex Whitespace, collapsed around continuations +@cindex Collapsing whitespace around continuations +In general, any number of spaces or tabs before the @code{@@} +continuation character are collapsed into a single space. There is one +exception: the Texinfo processors will not fully collapse whitespace +around a continuation inside braces. For example: + +@example +@@deffn @{Category @@ + Name@} @dots{} +@end example + +@noindent The output (not shown) has excess space between `Category' +and `Name'. To avoid this, elide the unwanted whitespace in your +input, or put the continuation @code{@@} outside braces. + +@code{@@} does not function as a continuation character in @emph{any} +other context. Ordinarily, @samp{@@} followed by a whitespace +character (space, tab, newline) produces a normal interword space +(@pxref{Multiple Spaces}). + + +@node Optional Arguments +@section Optional and Repeated Arguments +@cindex Optional and repeated arguments +@cindex Repeated and optional arguments +@cindex Arguments, repeated and optional +@cindex Syntax, optional & repeated arguments +@cindex Meta-syntactic chars for arguments + +@c This is consistent with the Emacs Lisp Reference Manual. +Some entities take optional or repeated arguments, conventionally +specified by using square brackets and ellipses: an argument enclosed +within square brackets is optional, and an argument followed by an +ellipsis is optional and may be repeated more than once. + +Thus, [@var{optional-arg}] means that @var{optional-arg} is optional +and @var{repeated-args}@code{@dots{}} stands for zero or more +arguments. Parentheses are used when several arguments are grouped +into additional levels of list structure in Lisp. + +Here is the @code{@@defspec} line of an example of an imaginary +(complicated) special form: + +@quotation +@defspec foobar (var [from to [inc]]) body@dots{} +@end defspec +@end quotation + +@noindent +In this example, the arguments @var{from} and @var{to} are optional, +but must both be present or both absent. If they are present, +@var{inc} may optionally be specified as well. These arguments are +grouped with the argument @var{var} into a list, to distinguish them +from @var{body}, which includes all remaining elements of the +form. + +In a Texinfo source file, this @code{@@defspec} line is written like +this: + +@example +@@defspec foobar (var [from to [inc]]) body@@dots@{@} +@end example + +@noindent +The function is listed in the Command and Variable Index under +@samp{foobar}. + + +@node @code{@@deffnx} +@section @code{@@deffnx}, et al.: Two or More `First' Lines + +@anchor{deffnx}@c old node +@findex deffnx +@cindex Two `First' Lines for @code{@@deffn} +@cindex Grouping two definitions together +@cindex Definitions grouped together + +To create two or more `first' or header lines for a definition, follow +the first @code{@@deffn} line by a line beginning with +@code{@@deffnx}. The @code{@@deffnx} command works exactly like +@code{@@deffn} except that it does not generate extra vertical white +space between it and the preceding line. + +@need 1000 +For example, + +@example +@group +@@deffn @{Interactive Command@} isearch-forward +@@deffnx @{Interactive Command@} isearch-backward +These two search commands are similar except @dots{} +@@end deffn +@end group +@end example + +@noindent +produces + +@deffn {Interactive Command} isearch-forward +@deffnx {Interactive Command} isearch-backward +These two search commands are similar except @dots{} +@end deffn + +@findex defcvx +@findex defivarx +@findex defmacx +@findex defmethodx +@findex defoptx +@findex defopx +@findex defspecx +@findex deftpx +@findex deftypecvx +@findex deftypefnx +@findex deftypefunx +@findex deftypeivarx +@findex deftypemethodx +@findex deftypeopx +@findex deftypevarx +@findex deftypevrx +@findex defunx +@findex defvarx +@findex defvrx +Each definition command has an `x' form: @code{@@defunx}, +@code{@@defvrx}, @code{@@deftypefunx}, etc. + +The `x' forms work similarly to @code{@@itemx} +(@pxref{@code{@@itemx}}). + + +@node Def Cmds in Detail +@section The Definition Commands + +Texinfo provides more than a dozen definition commands, all of which +are described in this section. + +The definition commands automatically enter the name of the entity in +the appropriate index: for example, @code{@@deffn}, @code{@@defun}, +and @code{@@defmac} enter function names in the index of functions; +@code{@@defvr} and @code{@@defvar} enter variable names in the index +of variables. + +Although the examples that follow mostly illustrate Lisp, the commands +can be used for other programming languages. + +@menu +* Functions Commands:: Commands for functions and similar entities. +* Variables Commands:: Commands for variables and similar entities. +* Typed Functions:: Commands for functions in typed languages. +* Typed Variables:: Commands for variables in typed languages. +* Data Types:: The definition command for data types. +* Abstract Objects:: Commands for object-oriented programming. +@end menu + +@node Functions Commands +@subsection Functions and Similar Entities + +This section describes the commands for describing functions and similar +entities: + +@table @code +@findex deffn +@item @@deffn @var{category} @var{name} @var{arguments}@dots{} +The @code{@@deffn} command is the general definition command for +functions, interactive commands, and similar entities that may take +arguments. You must choose a term to describe the category of entity +being defined; for example, ``Function'' could be used if the entity is +a function. The @code{@@deffn} command is written at the beginning of a +line and is followed on the same line by the category of entity being +described, the name of this particular entity, and its arguments, if +any. Terminate the definition with @code{@@end deffn} on a line of its +own. + +@need 750 +For example, here is a definition: + +@example +@group +@@deffn Command forward-char nchars +Move point forward @@var@{nchars@} characters. +@@end deffn +@end group +@end example + +@noindent +This shows a rather terse definition for a ``command'' named +@code{forward-char} with one argument, @var{nchars}. + +@code{@@deffn} prints argument names such as @var{nchars} in slanted +type in the printed output, because we think of these names as +metasyntactic variables---they stand for the actual argument values. +Within the text of the description, however, write an argument name +explicitly with @code{@@var} to refer to the value of the argument. +In the example above, we used @samp{@@var@{nchars@}} in this way. + +In the extremely unusual case when an argument name contains +@samp{--}, or another character sequence which is treated specially +(@pxref{Conventions}), use @code{@@code} around the special +characters. This avoids the conversion to typographic en-dashes and +em-dashes. +@c @var also works; that's what we used to recommend. + +The template for @code{@@deffn} is: + +@example +@group +@@deffn @var{category} @var{name} @var{arguments}@dots{} +@var{body-of-definition} +@@end deffn +@end group +@end example + +@findex defun +@item @@defun @var{name} @var{arguments}@dots{} +The @code{@@defun} command is the definition command for functions. +@code{@@defun} is equivalent to @samp{@@deffn Function @dots{}}. +Terminate the definition with @code{@@end defun} on a line of its own. +Thus, the template is: + +@example +@group +@@defun @var{function-name} @var{arguments}@dots{} +@var{body-of-definition} +@@end defun +@end group +@end example + +@findex defmac +@item @@defmac @var{name} @var{arguments}@dots{} +The @code{@@defmac} command is the definition command for macros. +@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and +works like @code{@@defun}. + +@findex defspec +@item @@defspec @var{name} @var{arguments}@dots{} +The @code{@@defspec} command is the definition command for special +forms. (In Lisp, a special form is an entity much like a function; +@pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.) +@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} +@dots{}} and works like @code{@@defun}. +@end table + +All these commands create entries in the index of functions. + + +@node Variables Commands +@subsection Variables and Similar Entities + +Here are the commands for defining variables and similar +entities: + +@table @code +@findex defvr +@item @@defvr @var{category} @var{name} +The @code{@@defvr} command is a general definition command for +something like a variable---an entity that records a value. You must +choose a term to describe the category of entity being defined; for +example, ``Variable'' could be used if the entity is a variable. +Write the @code{@@defvr} command at the beginning of a line and +follow it on the same line by the category of the entity and the +name of the entity. + +We recommend capitalizing the category name like a title. If the name +of the category contains spaces, as in the name ``User Option'', +enclose it in braces. Otherwise, the second word will be mistaken for +the name of the entity. For example, + +@example +@group +@@defvr @{User Option@} fill-column +This buffer-local variable specifies +the maximum width of filled lines. +@dots{} +@@end defvr +@end group +@end example + +Terminate the definition with @code{@@end defvr} on a line of its +own. + +The template is: + +@example +@group +@@defvr @var{category} @var{name} +@var{body-of-definition} +@@end defvr +@end group +@end example + +@code{@@defvr} creates an entry in the index of variables for @var{name}. + +@findex defvar +@item @@defvar @var{name} +The @code{@@defvar} command is the definition command for variables. +@code{@@defvar} is equivalent to @samp{@@defvr Variable +@dots{}}. + +@need 750 +For example: + +@example +@group +@@defvar kill-ring +@dots{} +@@end defvar +@end group +@end example + +The template is: + +@example +@group +@@defvar @var{name} +@var{body-of-definition} +@@end defvar +@end group +@end example + +@code{@@defvar} creates an entry in the index of variables for +@var{name}. + +@findex defopt +@item @@defopt @var{name} +@cindex User options, marking +The @code{@@defopt} command is the definition command for @dfn{user +options}, i.e., variables intended for users to change according to +taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs +Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User +Option@} @dots{}} and works like @code{@@defvar}. It creates an entry +in the index of variables. +@end table + + +@node Typed Functions +@subsection Functions in Typed Languages + +@cindex Typed functions +@cindex Functions, in typed languages + +The @code{@@deftypefn} command and its variations are for describing +functions in languages in which you must declare types of variables +and functions, such as C and C++. + +@table @code +@findex deftypefn +@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} +The @code{@@deftypefn} command is the general definition command for +functions and similar entities that may take arguments and that are +typed. The @code{@@deftypefn} command is written at the beginning of +a line and is followed on the same line by the category of entity +being described, the type of the returned value, the name of this +particular entity, and its arguments, if any. + +@need 800 +@noindent +For example, + +@example +@group +@@deftypefn @{Library Function@} int foobar @@ + (int @@var@{foo@}, float @@var@{bar@}) +@dots{} +@@end deftypefn +@end group +@end example + +produces: + +@quotation +@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) +@dots{} +@end deftypefn +@end quotation + +This means that @code{foobar} is a ``library function'' that returns an +@code{int}, and its arguments are @var{foo} (an @code{int}) and +@var{bar} (a @code{float}). + +Since in typed languages, the actual names of the arguments are +typically scattered among data type names and keywords, Texinfo cannot +find them without help. You can either (a)@tie{}write everything as +straight text, and it will be printed in slanted type; (b)@tie{}use +@code{@@var} for the variable names, which will uppercase the variable +names in Info and use the slanted typewriter font in printed output; +(c)@tie{}use @code{@@var} for the variable names and @code{@@code} for +the type names and keywords, which will be dutifully obeyed. + +The template for @code{@@deftypefn} is: + +@example +@group +@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{} +@var{body-of-description} +@@end deftypefn +@end group +@end example + +@noindent +Note that if the @var{category} or @var{data type} is more than one +word then it must be enclosed in braces to make it a single argument. + +If you are describing a procedure in a language that has packages, +such as Ada, you might consider using @code{@@deftypefn} in a manner +somewhat contrary to the convention described in the preceding +paragraphs. For example: + +@example +@group +@@deftypefn stacks private push @@ + (@@var@{s@}:in out stack; @@ + @@var@{n@}:in integer) +@dots{} +@@end deftypefn +@end group +@end example + +@noindent +(In these examples the @code{@@deftypefn} arguments are shown using +continuations (@pxref{Def Cmd Continuation Lines}), but could be on a +single line.) + +In this instance, the procedure is classified as belonging to the +package @code{stacks} rather than classified as a `procedure' and its +data type is described as @code{private}. (The name of the procedure +is @code{push}, and its arguments are @var{s} and @var{n}.) + +@code{@@deftypefn} creates an entry in the index of functions for +@var{name}. + +@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{} +@findex deftypefun +The @code{@@deftypefun} command is the specialized definition command +for functions in typed languages. The command is equivalent to +@samp{@@deftypefn Function @dots{}}. The template is: + +@example +@group +@@deftypefun @var{type} @var{name} @var{arguments}@dots{} +@var{body-of-description} +@@end deftypefun +@end group +@end example + +@code{@@deftypefun} creates an entry in the index of functions for +@var{name}. + +@end table + +@cindex Return type, own line for +@findex deftypefnnewline +Ordinarily, the return type is printed on the same line as the +function name and arguments, as shown above. In source code, GNU +style is to put the return type on a line by itself. So Texinfo +provides an option to do that: @code{@@deftypefnnewline on}. + +This affects typed functions only---not untyped functions, not typed +variables, etc.. Specifically, it affects the commands in this +section, and the analogous commands for object-oriented languages, +namely @code{@@deftypeop} and @code{@@deftypemethod} +(@pxref{Object-Oriented Methods}). + +Specifying @code{@@deftypefnnewline off} reverts to the default. + + +@node Typed Variables +@subsection Variables in Typed Languages + +@cindex Typed variables +@cindex Variables, in typed languages + +Variables in typed languages are handled in a manner similar to +functions in typed languages. @xref{Typed Functions}. The general +definition command @code{@@deftypevr} corresponds to +@code{@@deftypefn} and the specialized definition command +@code{@@deftypevar} corresponds to @code{@@deftypefun}. + +@table @code +@findex deftypevr +@item @@deftypevr @var{category} @var{data-type} @var{name} +The @code{@@deftypevr} command is the general definition command for +something like a variable in a typed language---an entity that records +a value. You must choose a term to describe the category of the +entity being defined; for example, ``Variable'' could be used if the +entity is a variable. + +The @code{@@deftypevr} command is written at the beginning of a line +and is followed on the same line by the category of the entity +being described, the data type, and the name of this particular +entity. + +@need 800 +@noindent +For example: + +@example +@group +@@deftypevr @{Global Flag@} int enable +@dots{} +@@end deftypevr +@end group +@end example + +@noindent +produces the following: + +@quotation +@deftypevr {Global Flag} int enable +@dots{} +@end deftypevr +@end quotation + +@need 800 +The template is: + +@example +@@deftypevr @var{category} @var{data-type} @var{name} +@var{body-of-description} +@@end deftypevr +@end example + +@findex deftypevar +@item @@deftypevar @var{data-type} @var{name} +The @code{@@deftypevar} command is the specialized definition command +for variables in typed languages. @code{@@deftypevar} is equivalent +to @samp{@@deftypevr Variable @dots{}}. The template is: + +@example +@group +@@deftypevar @var{data-type} @var{name} +@var{body-of-description} +@@end deftypevar +@end group +@end example +@end table + +These commands create entries in the index of variables. + + +@node Data Types +@subsection Data Types + +Here is the command for data types: + +@table @code +@findex deftp +@item @@deftp @var{category} @var{name} @var{attributes}@dots{} +The @code{@@deftp} command is the generic definition command for data +types. The command is written at the beginning of a line and is +followed on the same line by the category, by the name of the type +(which is a word like @code{int} or @code{float}), and then by names of +attributes of objects of that type. Thus, you could use this command +for describing @code{int} or @code{float}, in which case you could use +@code{data type} as the category. (A data type is a category of +certain objects for purposes of deciding which operations can be +performed on them.) + +In Lisp, for example, @dfn{pair} names a particular data +type, and an object of that type has two slots called the +@sc{car} and the @sc{cdr}. Here is how you would write the first line +of a definition of @code{pair}. + +@example +@group +@@deftp @{Data type@} pair car cdr +@dots{} +@@end deftp +@end group +@end example + +@need 950 +The template is: + +@example +@group +@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} +@var{body-of-definition} +@@end deftp +@end group +@end example + +@code{@@deftp} creates an entry in the index of data types. +@end table + + +@node Abstract Objects +@subsection Object-Oriented Programming + +@cindex Object-oriented programming + +Here are the commands for formatting descriptions about abstract +objects, such as are used in object-oriented programming. A class is +a defined type of abstract object. An instance of a class is a +particular object that has the type of the class. An instance +variable is a variable that belongs to the class but for which each +instance has its own value. + +@menu +* Variables: Object-Oriented Variables. +* Methods: Object-Oriented Methods. +@end menu + + +@node Object-Oriented Variables +@subsubsection Object-Oriented Variables + +@cindex Variables, object-oriented + +These commands allow you to define different sorts of variables in +object-oriented programming languages. + +@table @code +@item @@defcv @var{category} @var{class} @var{name} +@findex defcv +The @code{@@defcv} command is the general definition command for +variables associated with classes in object-oriented programming. The +@code{@@defcv} command is followed by three arguments: the category of +thing being defined, the class to which it belongs, and its +name. For instance: + +@example +@group +@@defcv @{Class Option@} Window border-pattern +@dots{} +@@end defcv +@end group +@end example + +@noindent produces: +@defcv {Class Option} Window border-pattern +@dots{} +@end defcv + +@code{@@defcv} creates an entry in the index of variables. + +@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name} +@findex deftypecv +The @code{@@deftypecv} command is the definition command for typed +class variables in object-oriented programming. It is analogous to +@code{@@defcv} with the addition of the @var{data-type} parameter to +specify the type of the instance variable. Ordinarily, the data type +is a programming language construct that should be marked with +@code{@@code}. For instance: + +@example +@group +@@deftypecv @{Class Option@} Window @@code@{int@} border-pattern +@dots{} +@@end deftypecv +@end group +@end example + +@noindent produces: + +@deftypecv {Class Option} Window @code{int} border-pattern +@dots{} +@end deftypecv + +@code{@@deftypecv} creates an entry in the index of variables. + +@item @@defivar @var{class} @var{name} +@findex defivar +The @code{@@defivar} command is the definition command for instance +variables in object-oriented programming. @code{@@defivar} is +equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}. For +instance: + +@example +@group +@@defivar Window border-pattern +@dots{} +@@end defivar +@end group +@end example + +@noindent produces: + +@defivar Window border-pattern +@dots{} +@end defivar + +@code{@@defivar} creates an entry in the index of variables. + +@item @@deftypeivar @var{class} @var{data-type} @var{name} +@findex deftypeivar +The @code{@@deftypeivar} command is the definition command for typed +instance variables in object-oriented programming. It is analogous to +@code{@@defivar} with the addition of the @var{data-type} parameter to +specify the type of the instance variable. Ordinarily, the data type +is a programming language construct that should be marked with +@code{@@code}. For instance: + +@example +@group +@@deftypeivar Window @@code@{int@} border-pattern +@dots{} +@@end deftypeivar +@end group +@end example + +@noindent produces: + +@deftypeivar Window @code{int} border-pattern +@dots{} +@end deftypeivar + +@code{@@deftypeivar} creates an entry in the index of variables. + +@end table + + +@node Object-Oriented Methods +@subsubsection Object-Oriented Methods + +@cindex Methods, object-oriented + +These commands allow you to define different sorts of function-like +entities resembling methods in object-oriented programming languages. +These entities take arguments, as functions do, but are associated with +particular classes of objects. + +@table @code + +@findex defop +@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} +The @code{@@defop} command is the general definition command for these +method-like entities. + +For example, some systems have constructs called @dfn{wrappers} that +are associated with classes as methods are, but that act more like +macros than like functions. You could use @code{@@defop Wrapper} to +describe one of these. + +Sometimes it is useful to distinguish methods and @dfn{operations}. +You can think of an operation as the specification for a method. +Thus, a window system might specify that all window classes have a +method named @code{expose}; we would say that this window system +defines an @code{expose} operation on windows in general. Typically, +the operation has a name and also specifies the pattern of arguments; +all methods that implement the operation must accept the same +arguments, since applications that use the operation do so without +knowing which method will implement it. + +Often it makes more sense to document operations than methods. For +example, window application developers need to know about the +@code{expose} operation, but need not be concerned with whether a +given class of windows has its own method to implement this operation. +To describe this operation, you would write: + +@example +@@defop Operation windows expose +@end example + +The @code{@@defop} command is written at the beginning of a line and +is followed on the same line by the overall name of the category of +operation, the name of the class of the operation, the name of the +operation, and its arguments, if any. + +The template is: +@example +@group +@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} +@var{body-of-definition} +@@end defop +@end group +@end example + +@code{@@defop} creates an entry, such as `@code{expose} on +@code{windows}', in the index of functions. + +@findex deftypeop +@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} +The @code{@@deftypeop} command is the definition command for typed +operations in object-oriented programming. It is similar to +@code{@@defop} with the addition of the @var{data-type} parameter to +specify the return type of the method. @code{@@deftypeop} creates an +entry in the index of functions. + +@item @@defmethod @var{class} @var{name} @var{arguments}@dots{} +@findex defmethod +The @code{@@defmethod} command is the definition command for methods +in object-oriented programming. A method is a kind of function that +implements an operation for a particular class of objects and its +subclasses. +@ignore +@c ADR: Who cares?!? +@c KB: Oh, I don't know, I think this info is crucial! +In the Lisp Machine, methods actually were functions, but +they were usually defined with @code{defmethod}. +@end ignore + +@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. +The command is written at the beginning of a line and is followed by +the name of the class of the method, the name of the method, and its +arguments, if any. + +@noindent +For example: +@example +@group +@@defmethod @code{bar-class} bar-method argument +@dots{} +@@end defmethod +@end group +@end example + +@noindent +illustrates the definition for a method called @code{bar-method} of +the class @code{bar-class}. The method takes an argument. + +@code{@@defmethod} creates an entry in the index of functions. + +@item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{} +@findex deftypemethod +The @code{@@deftypemethod} command is the definition command for methods +in object-oriented typed languages, such as C++ and Java. It is similar +to the @code{@@defmethod} command with the addition of the +@var{data-type} parameter to specify the return type of the method. +@code{@@deftypemethod} creates an entry in the index of functions. + +@end table + +The typed commands are affected by the @code{@@deftypefnnewline} +option (@pxref{Typed Functions,, Functions in Typed Languages}). + + +@node Def Cmd Conventions +@section Conventions for Writing Definitions +@cindex Definition conventions +@cindex Conventions for writing definitions + +When you write a definition using @code{@@deffn}, @code{@@defun}, or +one of the other definition commands, please take care to use +arguments that indicate the meaning, as with the @var{count} argument +to the @code{forward-word} function. Also, if the name of an argument +contains the name of a type, such as @var{integer}, take care that the +argument actually is of that type. + + +@node Sample Function Definition +@section A Sample Function Definition +@cindex Function definitions +@cindex Command definitions +@cindex Macro definitions, programming-language +@cindex Sample function definition + +A function definition uses the @code{@@defun} and @code{@@end defun} +commands. The name of the function follows immediately after the +@code{@@defun} command and it is followed, on the same line, by the +parameter list. + +Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs +Lisp Reference Manual}. + +@quotation +@defun apply function &rest arguments +@code{apply} calls @var{function} with @var{arguments}, just +like @code{funcall} but with one difference: the last of +@var{arguments} is a list of arguments to give to +@var{function}, rather than a single argument. We also say +that this list is @dfn{appended} to the other arguments. + +@code{apply} returns the result of calling @var{function}. +As with @code{funcall}, @var{function} must either be a Lisp +function or a primitive function; special forms and macros +do not make sense in @code{apply}. + +@example +(setq f 'list) + @result{} list +(apply f 'x 'y 'z) +@error{} Wrong type argument: listp, z +(apply '+ 1 2 '(3 4)) + @result{} 10 +(apply '+ '(1 2 3 4)) + @result{} 10 + +(apply 'append '((a b c) nil (x y z) nil)) + @result{} (a b c x y z) +@end example + +An interesting example of using @code{apply} is found in the description +of @code{mapcar}. +@end defun +@end quotation + +In the Texinfo source file, this example looks like this: + +@example +@group +@@defun apply function &rest arguments +@@code@{apply@} calls @@var@{function@} with +@@var@{arguments@}, just like @@code@{funcall@} but with one +difference: the last of @@var@{arguments@} is a list of +arguments to give to @@var@{function@}, rather than a single +argument. We also say that this list is @@dfn@{appended@} +to the other arguments. +@end group + +@group +@@code@{apply@} returns the result of calling +@@var@{function@}. As with @@code@{funcall@}, +@@var@{function@} must either be a Lisp function or a +primitive function; special forms and macros do not make +sense in @@code@{apply@}. +@end group + +@group +@@example +(setq f 'list) + @@result@{@} list +(apply f 'x 'y 'z) +@@error@{@} Wrong type argument: listp, z +(apply '+ 1 2 '(3 4)) + @@result@{@} 10 +(apply '+ '(1 2 3 4)) + @@result@{@} 10 + +(apply 'append '((a b c) nil (x y z) nil)) + @@result@{@} (a b c x y z) +@@end example +@end group + +@group +An interesting example of using @@code@{apply@} is found +in the description of @@code@{mapcar@}. +@@end defun +@end group +@end example + +@noindent +In this manual, this function is listed in the Command and Variable +Index under @code{apply}. + +Ordinary variables and user options are described using a format like +that for functions except that variables do not take arguments. + + +@node Internationalization +@chapter Internationalization + +@cindex Internationalization +Texinfo has some support for writing in languages other than English, +although this area still needs considerable work. (If you are +the one helping to translate the fixed strings written to documents, +@pxref{Internationalization of Document Strings}.) + +For a list of the various accented and special characters Texinfo +supports, see @ref{Inserting Accents}. + +@menu +* @code{@@documentlanguage}:: Declaring the current language. +* @code{@@documentencoding}:: Declaring the input encoding. +@end menu + + +@node @code{@@documentlanguage} +@section @code{@@documentlanguage @var{ll}[_@var{cc}]}: Set the Document Language +@anchor{documentlanguage} + +@findex documentlanguage +@cindex Language, declaring +@cindex Locale, declaring +@cindex Document language, declaring + +The @code{@@documentlanguage} command declares the current document +locale. Write it on a line by itself, near the beginning of the file. + +@example +@@documentlanguage @var{ll}[_@var{cc}] +@end example + +Include a two-letter ISO@tie{}639-2 language code (@var{ll}) following +the command name, optionally followed by an underscore and two-letter +ISO@tie{}3166 two-letter country code (@var{cc}). If you have a +multilingual document, the intent is to be able to use this command +multiple times, to declare each language change. If the command is +not used at all, the default is @code{en_US} for US English. + +As with GNU Gettext (@pxref{Top,,, gettext, Gettext}), if the country +code is omitted, the main dialect is assumed where possible. For +example, @code{de} is equivalent to @code{de_DE} (German as spoken in +Germany). + +@cindex Document strings, translation of +For Info and other online output, this command changes the translation +of various @dfn{document strings} such as ``see'' in cross-references +(@pxref{Cross References}), ``Function'' in defuns (@pxref{Definition +Commands}), and so on. Some strings, such as ``Node:'', ``Next:'', +``Menu:'', etc., are keywords in Info output, so are not translated +there; they are translated in other output formats. + +@cindex @file{txi-@var{cc}.tex} +For @TeX{}, this command causes a file @file{txi-@var{locale}.tex} to +be read (if it exists). If @code{@@documentlanguage} argument +contains the optional @samp{_@var{cc}} suffix, this is tried first. +For example, with @code{@@documentlanguage de_DE}, @TeX{} first looks +for @file{txi-de_DE.tex}, then @file{txi-de.tex}. + +Such a @file{txi-*} file is intended to redefine the various English +words used in @TeX{} output, such as `Chapter', `See', and so on. We +are aware that individual words like these cannot always be translated +in isolation, and that a very different strategy would be required for +ideographic (among other) scripts. Help in improving Texinfo's +language support is welcome. + +@cindex Hyphenation patterns, language-dependent +@code{@@documentlanguage} also changes @TeX{}'s current hyphenation +patterns, if the @TeX{} program being run has the necessary support +included. This will generally not be the case for @command{tex} +itself, but will usually be the case for up-to-date distributions of +the extended @TeX{} programs @command{etex} (DVI output) and +@command{pdftex} (PDF output). @command{texi2dvi} will use the +extended @TeX{}s if they are available (@pxref{Format with +@command{texi2dvi}}). + +In September 2006, the W3C Internationalization Activity released a +new recommendation for specifying languages: +@url{http://www.rfc-editor.org/rfc/bcp/bcp47.txt}. When Gettext +supports this new scheme, Texinfo will too. + +@cindex ISO 639-2 language codes +@cindex ISO 3166 country codes +@cindex Language codes +@cindex Country codes +Since the lists of language codes and country codes are updated +relatively frequently, we don't attempt to list them here. The valid +language codes are on the official home page for ISO@tie{}639, +@url{http://www.loc.gov/standards/iso639-2/}. The country codes and +the official web site for ISO@tie{}3166 can be found via +@url{http://en.wikipedia.org/wiki/ISO_3166}. + + +@node @code{@@documentencoding} +@section @code{@@documentencoding @var{enc}}: Set Input Encoding + +@anchor{documentencoding}@c old name +@findex documentencoding +@cindex Encoding, declaring +@cindex Input encoding, declaring +@cindex Character set, declaring +@cindex Document input encoding + +The @code{@@documentencoding} command declares the input document +encoding, and can also affect the encoding of the output. Write it on +a line by itself, with a valid encoding specification following, near +the beginning of the file. + +@example +@@documentencoding @var{enc} +@end example + +Texinfo supports these encodings: + +@table @code +@item US-ASCII +This has no particular effect, but it's included for completeness. + +@item UTF-8 +The vast global character encoding, expressed in 8-bit bytes. + +@item ISO-8859-1 +@itemx ISO-8859-15 +@itemx ISO-8859-2 +@cindex Euro symbol, and encodings +These specify the standard encodings for Western European (the first +two) and Eastern European languages (the third), respectively. ISO +8859-15 replaces some little-used characters from 8859-1 (e.g., +precomposed fractions) with more commonly needed ones, such as the +Euro symbol (@euro{}). + +A full description of the encodings is beyond our scope here; +one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}. + +@item koi8-r +This is the commonly used encoding for the Russian language. + +@item koi8-u +This is the commonly used encoding for the Ukrainian language. + +@end table + +Specifying an encoding @var{enc} has the following effects: + +@cindex Local Variables section, for encoding +@cindex Info output, and encoding +In Info output, a so-called `Local Variables' section (@pxref{File +Variables,,, emacs, The GNU Emacs Manual}) is output including +@var{enc}. This allows Info readers to set the encoding +appropriately. It looks like this: + +@example +Local Variables: +coding: @var{enc} +End: +@end example + +Also, in Info and plain text output, unless the option +@option{--disable-encoding} is given to @command{makeinfo}, accent +constructs and special characters, such as @code{@@'e}, are output as +the actual 8-bit or UTF-8 character in the given encoding where +possible. + +@cindex HTML output, and encodings +@cindex @code{http-equiv}, and charset specification +@cindex @code{<meta>} HTML tag, and charset specification +In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>} +section of the HTML, that specifies @var{enc}. Web servers and +browsers cooperate to use this information so the correct encoding is +used to display the page, if supported by the system. That looks like +this: + +@example +<meta http-equiv="Content-Type" content="text/html; + charset=@var{enc}"> +@end example + +In XML and Docbook output, UTF-8 is always used for the output, +according to the conventions of those formats. + +@cindex Computer Modern fonts +In @TeX{} output, the characters which are supported in the standard +Computer Modern fonts are output accordingly. For example, this +means using constructed accents rather than precomposed glyphs. +Using a missing character generates a warning message, as does +specifying an unimplemented encoding. + +Although modern @TeX{} systems support nearly every script in use in +the world, this wide-ranging support is not available in +@file{texinfo.tex}, and it's not feasible to duplicate or incorporate +all that effort. (Our plan to support other scripts is to create a +@LaTeX{} back-end to @command{texi2any}, where the support is already +present.) + +For maximum portability of Texinfo documents across the many different +user environments in the world, we recommend sticking to 7-bit ASCII +in the input unless your particular manual needs a substantial amount +of non-ASCII, e.g., it's written in German. You can use the +@code{@@U} command to insert an occasional needed character +(@pxref{Inserting Unicode}). + + +@node Conditionals +@chapter Conditionally Visible Text +@cindex Conditionally visible text +@cindex Text, conditionally visible +@cindex Visibility of conditional text +@cindex If text conditionally visible + +The @dfn{conditional commands} allow you to use different text for +different output formats, or for general conditions that you define. +For example, you can use them to specify different text for the +printed manual and the Info output. + +The conditional commands comprise the following categories. + +@itemize @bullet +@item +Commands specific to an output format (Info, @TeX{}, HTML, @dots{}). + +@item +Commands specific to any output format @emph{excluding} a given +one (e.g., not Info, not @TeX{}, @dots{}). + +@item +`Raw' formatter text for any output format, passed straight +through with minimal (but not zero) interpretation of @@-commands. + +@item +Format-independent variable substitutions, and testing if a variable +is set or clear. + +@end itemize + +@menu +* Conditional Commands:: Text for a given format. +* Conditional Not Commands:: Text for any format other than a given one. +* Raw Formatter Commands:: Using raw formatter commands. +* Inline Conditionals:: Brace-delimited conditional text. +* @code{@@set @@clear @@value}:: Variable tests and substitutions. +* Testing for Texinfo Commands:: Testing if a Texinfo command is available. +* Conditional Nesting:: Using conditionals inside conditionals. +@end menu + + +@node Conditional Commands +@section Conditional Commands + +Texinfo has an @code{@@if@var{format}} environment for each output +format, to allow conditional inclusion of text for a particular output +format. + +@findex ifinfo +@code{@@ifinfo} begins segments of text that should be ignored by +@TeX{} when it typesets the printed manual, and by @command{makeinfo} +when not producing Info output. The segment of text appears only in +the Info file and, for historical compatibility, the plain text +output. + +@findex ifdocbook +@findex ifhtml +@findex ifplaintext +@findex iftex +@findex ifxml +The environments for the other formats are analogous: + +@table @code +@item @@ifdocbook @dots{} @@end ifdocbook +Text to appear only in the Docbook output. + +@item @@ifhtml @dots{} @@end ifhtml +Text to appear only in the HTML output. + +@item @@ifplaintext @dots{} @@end ifplaintext +Text to appear only in the plain text output. + +@item @@iftex @dots{} @@end iftex +Text to appear only in the printed manual. + +@item @@ifxml @dots{} @@end ifxml +Text to appear only in the XML output. +@end table + +The @code{@@if@dots{}} and @code{@@end if@dots{}} commands must appear +on lines by themselves in your source file. The newlines following +the commands are (more or less) treated as whitespace, so that the +conditional text is flowed normally into a surrounding paragraph. + +The @code{@@if@dots{}} constructs are intended to conditionalize +normal Texinfo source; @pxref{Raw Formatter Commands}, for using +underlying format commands directly. + +Here is an example showing all these conditionals: + +@example +@@iftex +This text will appear only in the printed manual. +@@end iftex +@@ifinfo +However, this text will appear only in Info and plain text. +@@end ifinfo +@@ifhtml +And this text will only appear in HTML. +@@end ifhtml +@@ifplaintext +Whereas this text will only appear in plain text. +@@end ifplaintext +@@ifxml +Notwithstanding that this will only appear in XML@. +@@end ifxml +@@ifdocbook +Nevertheless, this will only appear in Docbook. +@@end ifdocbook +@end example + +@noindent +The preceding example produces the following line: + +@iftex +This text will appear only in the printed manual. +@end iftex +@ifinfo +However, this text will appear only in Info and plain text. +@end ifinfo +@ifhtml +And this text will only appear in HTML. +@end ifhtml +@ifplaintext +Whereas this text will only appear in plain text. +@end ifplaintext +@ifxml +Notwithstanding that this will only appear in XML@. +@end ifxml +@ifdocbook +Nevertheless, this will only appear in Docbook. +@end ifdocbook + +@noindent +Notice that you only see one of the input lines, depending on which +version of the manual you are reading. + +@findex errormsg +In complex documents, you may want Texinfo to issue an error message +in some conditionals that should not ever be processed. The +@code{@@errormsg@{@var{text}@}} command will do this; it takes one +argument, the text of the error message. + +We mention @code{@@errormsg@{@}} here even though it is not strictly +related to conditionals, since in practice it is most likely to be +useful in that context. Technically, it can be used anywhere. +@xref{External Macro Processors}, for a caveat regarding the line +numbers which @code{@@errormsg} emits in @TeX{}. + + +@node Conditional Not Commands +@section Conditional Not Commands +@findex ifnotdocbook +@findex ifnothtml +@findex ifnotinfo +@findex ifnotplaintext +@findex ifnottex +@findex ifnotxml + +You can specify text to be included in any output format @emph{other} +than a given one with the @code{@@ifnot@dots{}} environments: + +@example +@@ifnotdocbook @dots{} @@end ifnotdocbook +@@ifnothtml @dots{} @@end ifnothtml +@@ifnotinfo @dots{} @@end ifnotinfo +@@ifnotplaintext @dots{} @@end ifnotplaintext +@@ifnottex @dots{} @@end ifnottex +@@ifnotxml @dots{} @@end ifnotxml +@end example + +@noindent +The @code{@@ifnot@dots{}} command and the @code{@@end} command must +appear on lines by themselves in your actual source file. + +If the output file is being made in the given format, the +region is @emph{ignored}. Otherwise, it is included. + +There is one exception (for historical compatibility): +@code{@@ifnotinfo} text is omitted for both Info and plain text +output, not just Info. To specify text which appears only in Info and +not in plain text, use @code{@@ifnotplaintext}, like this: + +@example +@@ifinfo +@@ifnotplaintext +This will be in Info, but not plain text. +@@end ifnotplaintext +@@end ifinfo +@end example + +The regions delimited by these commands are ordinary Texinfo source as +with @code{@@iftex}, not raw formatter source as with @code{@@tex} +(@pxref{Raw Formatter Commands}). + + +@node Raw Formatter Commands +@section Raw Formatter Commands +@cindex Raw formatter commands + +@cindex @TeX{} commands, using ordinary +@cindex Ordinary @TeX{} commands, using +@cindex Commands using raw @TeX{} +@cindex Plain @TeX{} + +The @code{@@if@dots{}} conditionals just described must be used only +with normal Texinfo source. For instance, most features of plain +@TeX{} will not work within @code{@@iftex}. The purpose of +@code{@@if@dots{}} is to provide conditional processing for Texinfo +source, not provide access to underlying formatting features. For +that, Texinfo provides so-called @dfn{raw formatter commands}. They +should only be used when truly required (most documents do not need +them). + +@findex tex +@cindex Category codes, of plain @TeX{} +The first raw formatter command is @code{@@tex}. You can enter plain +@TeX{} completely, and use @samp{\} in the @TeX{} commands, by +delineating a region with the @code{@@tex} and @code{@@end tex} +commands. All plain @TeX{} commands and category codes are restored +within a @code{@@tex} region. The sole exception is that the +@code{@@} character still introduces a command, so that @code{@@end +tex} can be recognized. Texinfo processors will not output material +in such a region, unless @TeX{} output is being produced. + +@findex \gdef @r{within @code{@@tex}} +@findex \globaldefs @r{within @code{@@tex}} +In complex cases, you may wish to define new @TeX{} macros within +@code{@@tex}. You must use @code{\gdef} to do this, not @code{\def}, +because @code{@@tex} regions are processed in a @TeX{} group. If you +need to make several definitions, you may wish to set +@code{\globaldefs=1} (its value will be restored to zero as usual when +the group ends at @code{@@end tex}, so it won't cause problems with +the rest of the document). + +@cindex Equation, displayed, in plain @TeX{} +@cindex Displayed equation, in plain @TeX{} +As an example, here is a displayed equation written in plain @TeX{}: + +@example +@@tex +$$ \chi^2 = \sum_@{i=1@}^N + \left (y_i - (a + b x_i) + \over \sigma_i\right)^2 $$ +@@end tex +@end example + +@noindent +The output of this example will appear only in a printed manual. If +you are reading this in a format not generated by @TeX{}, you will not +see the equation that appears in the printed manual. + +@tex +$$ \chi^2 = \sum_{i=1}^N + \left(y_i - (a + b x_i) + \over \sigma_i\right)^2 $$ +@end tex + +@cindex HTML, including raw +@findex ifhtml +@findex html +Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to +delimit Texinfo source to be included in HTML output only, and +@code{@@html @dots{} @@end html} for a region of raw HTML. + +@cindex XML, including raw +@findex ifxml +@findex xml +Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit +Texinfo source to be included in XML output only, and @code{@@xml +@dots{} @@end xml} for a region of raw XML@. Regions of raw text in +other formats will also be present in the XML output, but with +protection of XML characters and within corresponding elements. For +example, the raw HTML text: + +@example +@group +@@html +<br /> +@@end html +@end group +@end example + +@noindent +will be included in the XML output as: + +@example +@group +<html> +<br /> +</html> +@end group +@end example + +@cindex Docbook, including raw +@findex ifdocbook +@findex docbook +Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook} +to delimit Texinfo source to be included in Docbook output only, and +@code{@@docbook @dots{} @@end docbook} for a region of raw Docbook. + +The behavior of newlines in raw regions is unspecified. + +In all cases, in raw processing, @code{@@} retains the same meaning as +in the remainder of the document. Thus, the Texinfo processors must +recognize and even execute, to some extent, the contents of the raw +regions, regardless of the final output format. Therefore, specifying +changes that globally affect the document inside a raw region leads to +unpredictable and generally undesirable behavior. For example, using +the @code{@@kbdinputstyle} command inside a raw region is undefined. + +The remedy is simple: don't do that. Use the raw formatter commands +for their intended purpose, of providing material directly in the +underlying format. When you simply want to give different Texinfo +specifications for different output formats, use the +@code{@@if@dots{}} conditionals and stay in Texinfo syntax. + + + +@node Inline Conditionals +@section Inline Conditionals: @code{@@inline}, @code{@@inlineifelse}, @code{@@inlineraw} +@findex inlinefmt +@findex inlinefmtifelse +@findex inlineraw +@cindex Inline conditionals +@cindex Conditional commands, inline +@cindex Brace-delimited conditional text +@cindex Newlines, avoiding in conditionals +@cindex Whitespace, controlling in conditionals + +Texinfo provides a set of conditional commands with arguments given +within braces: + +@table @code +@item @@inlinefmt@{@var{format}, @var{text}@} +Process the Texinfo @var{text} if @var{format} output is being +generated. + +@item @@inlinefmtifelse@{@var{format}, @var{then-text}, @var{else-text}@} +Process the Texinfo @var{then-text} if @var{format} output is being +generated; otherwise, process @var{else-text}. + +@item @@inlineraw@{@var{format}, @var{text}@} +Similar, but for raw @var{text} (@pxref{Raw Formatter Commands}). +@end table + +The supported @var{format} names are: + +@example +docbook html info plaintext tex xml +@end example + +For example, + +@example +@@inlinefmt@{html, @@emph@{HTML-only text@}@} +@end example + +@noindent is nearly equivalent to + +@example +@@ifhtml +@@emph@{HTML-only text@} +@@end ifhtml +@end example + +@noindent except that no whitespace is added, as happens in the latter +(environment) case. + +In these commands, whitespace is ignored after the comma separating +the arguments, as usual, but is @emph{not} ignored at the end of +@var{text}. + +To insert a literal at sign, left brace, or right brace in one of the +arguments, you must use the alphabetic commands @code{@@atchar@{@}} +(@pxref{Inserting an Atsign}), and @code{@@lbracechar@{@}} or +@code{@@rbracechar@{@}} (@pxref{Inserting Braces}), or the parsing +will become confused. + +With @code{@@inlinefmtifelse}, it is also necessary to use +@code{@@comma@{@}} to avoid mistaking a @samp{,} in the text for the +delimiter. With @code{@@inlinefmt} and @code{@@inlineraw}, +@code{@@comma@{@}} is not required (though it's fine to use it), since +these commands always have exactly two arguments. + +For @TeX{}, the processed @var{text} cannot contain newline-delimited +commands. Text to be ignored (i.e., for non-@TeX{}) can, though. + +Two other @code{@@inline...} conditionals complement the +@code{@@ifset} and @code{@@ifclear} commands; see the next section. + + +@node @code{@@set @@clear @@value} +@section Flags: @code{@@set}, @code{@@clear}, conditionals, and @code{@@value} + +@anchor{set clear value}@c old name +You can direct the Texinfo formatting commands to format or ignore parts +of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset}, +and @code{@@ifclear} commands. + +Here are brief descriptions of these commands, see the following +sections for more details: + +@table @code +@item @@set @var{flag} [@var{value}] +Set the variable @var{flag}, to the optional @var{value} if specified. + +@item @@clear @var{flag} +Undefine the variable @var{flag}, whether or not it was previously defined. + +@item @@ifset @var{flag} +If @var{flag} is set, text through the next @code{@@end ifset} command +is formatted. If @var{flag} is clear, text through the following +@code{@@end ifset} command is ignored. + +@item @@inlineifset@{@var{flag}, @var{text}@} +Brace-delimited version of @code{@@ifset}. + +@item @@ifclear @var{flag} +If @var{flag} is set, text through the next @code{@@end ifclear} command +is ignored. If @var{flag} is clear, text through the following +@code{@@end ifclear} command is formatted. + +@item @@inlineifclear@{@var{flag}, @var{text}@} +Brace-delimited version of @code{@@ifclear}. + +@end table + +@menu +* @code{@@set @@value}:: Expand a flag variable to a string. +* @code{@@ifset @@ifclear}:: Format a region if a flag is set. +* @code{@@inlineifset @@inlineifclear}:: Brace-delimited flag conditionals. +* @code{@@value} Example:: An easy way to update edition information. +@end menu + + +@node @code{@@set @@value} +@subsection @code{@@set} and @code{@@value} + +@anchor{set value}@c old name +@findex set +@findex value +@findex clear + +You use the @code{@@set} command to specify a value for a flag, which +is later expanded by the @code{@@value} command. + +A @dfn{flag} (aka @dfn{variable}) name is an identifier starting with +an alphanumeric, @samp{-}, or @samp{_}. Subsequent characters, if +any, may not be whitespace, @samp{@@}, braces, angle brackets, or any +of @samp{~`^+|}; other characters, such as @samp{%}, may work. +However, it is best to use only letters and numerals in a flag name, +not @samp{-} or @samp{_} or others---they will work in some contexts, +but not all, due to limitations in @TeX{}. + +The value is the remainder of the input line, and can contain anything. +However, unlike most other commands which take the rest of the line as +a value, @code{@@set} need not appear at the beginning of a line. + +Write the @code{@@set} command like this: + +@example +@@set foo This is a string. +@end example + +@noindent +This sets the value of the flag @code{foo} to ``This is a string.''. + +The Texinfo formatters then replace a @code{@@value@{@var{flag}@}} +command with the string to which @var{flag} is set. Thus, when +@code{foo} is set as shown above, the Texinfo formatters convert this: + +@example +@group +@@value@{foo@} +@exdent @r{to this:} +This is a string. +@end group +@end example + +You can write a @code{@@value} command within a paragraph; but you +must write a @code{@@set} command on a line of its own. + +If you write the @code{@@set} command like this: + +@example +@@set foo +@end example + +@noindent +without specifying a string, the value of @code{foo} is the empty string. + +If you clear a previously set flag with @code{@@clear @var{flag}}, a +subsequent @code{@@value@{flag@}} command will report an error. + +For example, if you set @code{foo} as follows: + +@example +@@set howmuch very, very, very +@end example + +@noindent +then the formatters transform + +@example +@group +It is a @@value@{howmuch@} wet day. +@exdent @r{into} +It is a very, very, very wet day. +@end group +@end example + +If you write + +@example +@@clear howmuch +@end example + +@noindent +then the formatters transform + +@example +@group +It is a @@value@{howmuch@} wet day. +@exdent @r{into} +It is a @{No value for "howmuch"@} wet day. +@end group +@end example + +@code{@@value} cannot be reliably used as the argument to an accent +command (@pxref{Inserting Accents}). For example, this fails: + +@example +@@set myletter a +@@'@@value@{myletter@} @c fails! +@end example + + +@node @code{@@ifset @@ifclear} +@subsection @code{@@ifset} and @code{@@ifclear} + +@anchor{ifset ifclear}@c old name +@findex ifset + +When a @var{flag} is set, the Texinfo formatting commands format text +between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end +ifset} commands. When the @var{flag} is cleared, the Texinfo formatting +commands do @emph{not} format the text. @code{@@ifclear} operates +analogously. + +Write the conditionally formatted text between @code{@@ifset @var{flag}} +and @code{@@end ifset} commands, like this: + +@example +@group +@@ifset @var{flag} +@var{conditional-text} +@@end ifset +@end group +@end example + +For example, you can create one document that has two variants, such as +a manual for a `large' and `small' model: + +@cindex Shrubbery +@example +You can use this machine to dig up shrubs +without hurting them. + +@@set large + +@@ifset large +It can also dig up fully grown trees. +@@end ifset + +Remember to replant promptly @dots{} +@end example + +@noindent +In the example, the formatting commands will format the text between +@code{@@ifset large} and @code{@@end ifset} because the @code{large} +flag is set. + +When @var{flag} is cleared, the Texinfo formatting commands do +@emph{not} format the text between @code{@@ifset @var{flag}} and +@code{@@end ifset}; that text is ignored and does not appear in either +printed or Info output. + +For example, if you clear the flag of the preceding example by writing +an @code{@@clear large} command after the @code{@@set large} command +(but before the conditional text), then the Texinfo formatting commands +ignore the text between the @code{@@ifset large} and @code{@@end ifset} +commands. In the formatted output, that text does not appear; in both +printed and Info output, you see only the lines that say, ``You can use +this machine to dig up shrubs without hurting them. Remember to replant +promptly @dots{}''. + +@findex ifclear +If a flag is cleared with a @code{@@clear @var{flag}} command, then +the formatting commands format text between subsequent pairs of +@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag +is set with @code{@@set @var{flag}}, then the formatting commands do +@emph{not} format text between an @code{@@ifclear} and an @code{@@end +ifclear} command; rather, they ignore that text. An @code{@@ifclear} +command looks like this: + +@example +@@ifclear @var{flag} +@end example + + +@node @code{@@inlineifset @@inlineifclear} +@subsection @code{@@inlineifset} and @code{@@inlineifclear} + +@findex inlineifset +@findex inlineifclear +@cindex Flag conditionals, brace-delimited +@cindex Brace-delimited flag conditionals + +@code{@@inlineifset} and @code{@@inlineifclear} provide +brace-delimited alternatives to the @code{@@ifset} and +@code{@@ifclear} forms, similar to the other @code{@@inline...} +Commands (@pxref{Inline Conditionals}). The same caveats about +argument parsing given there apply here too. + +@table @code +@item @@inlineifset@{@var{var}, @var{text}@} +Process the Texinfo @var{text} if the flag @var{var} is defined. + +@item @@inlineifclear@{@var{var}, @var{text}@} +Process the Texinfo @var{text} if the flag @var{var} is not defined. +@end table + +Except for the syntax, their general behavior and purposes is the same +as with @code{@@ifset} and @code{@@ifclear}, described in the previous +section. + + +@node @code{@@value} Example +@subsection @code{@@value} Example + +@anchor{value Example}@c old name + +You can use the @code{@@value} command to minimize the number of +places you need to change when you record an update to a manual. +@xref{GNU Sample Texts}, for the full text of an example of using this +to work with Automake distributions. + +This example is adapted from @ref{Top,,, make, The GNU Make Manual}. + +@enumerate +@item +Set the flags: + +@example +@group +@@set EDITION 0.35 Beta +@@set VERSION 3.63 Beta +@@set UPDATED 14 August 1992 +@@set UPDATE-MONTH August 1992 +@end group +@end example + +@item +Write text for the @code{@@copying} section (@pxref{@code{@@copying}}): + +@example +@group +@@copying +This is Edition @@value@{EDITION@}, +last updated @@value@{UPDATED@}, +of @@cite@{The GNU Make Manual@}, +for @@code@{make@}, version @@value@{VERSION@}. + +Copyright @dots{} + +Permission is granted @dots{} +@@end copying +@end group +@end example + +@item +Write text for the title page, for people reading the printed manual: + +@example +@group +@@titlepage +@@title GNU Make +@@subtitle A Program for Directing Recompilation +@@subtitle Edition @@value@{EDITION@}, @dots{} +@@subtitle @@value@{UPDATE-MONTH@} +@@page +@@insertcopying +@dots{} +@@end titlepage +@end group +@end example + +@noindent +(On a printed cover, a date listing the month and the year looks less +fussy than a date listing the day as well as the month and year.) + +@item +Write text for the Top node, for people reading the Info file: + +@example +@group +@@ifnottex +@@node Top +@@top Make + +This is Edition @@value@{EDITION@}, +last updated @@value@{UPDATED@}, +of @@cite@{The GNU Make Manual@}, +for @@code@{make@}, version @@value@{VERSION@}. +@@end ifnottex +@end group +@end example + +After you format the manual, the @code{@@value} constructs have been +expanded, so the output contains text like this: + +@example +@group +This is Edition 0.35 Beta, last updated 14 August 1992, +of `The GNU Make Manual', for `make', Version 3.63 Beta. +@end group +@end example +@end enumerate + +When you update the manual, you change only the values of the flags; you +do not need to edit the three sections. + + +@node Testing for Texinfo Commands +@section Testing for Texinfo Commands: @code{@@ifcommanddefined}, @code{@@ifcommandnotdefined} + +@cindex Testing for Texinfo commands +@cindex Checking for Texinfo commands +@cindex Texinfo commands, testing for +@cindex Commands, testing for Texinfo +@cindex Versions of Texinfo, adapting to +@cindex Features of Texinfo, adapting to +@findex ifcommanddefined +@findex ifcommandnotdefined + +Occasionally, you may want to arrange for your manual to test if a +given Texinfo command is available and (presumably) do some sort of +fallback formatting if not. There are conditionals +@code{@@ifcommanddefined} and @code{@@ifcommandnotdefined} to do this. +For example: + +@example +@@ifcommanddefined node +Good, @@samp@{@@@@node@} is defined. +@@end ifcommanddefined +@end example + +@noindent will output the expected `Good, @samp{@@node} is defined.'. + +This conditional will also consider any new commands defined by +the document via @code{@@macro}, @code{@@alias}, +@code{@@definfoenclose}, and @code{@@def@r{(}code@r{)}index} +(@pxref{Defining New Texinfo Commands}) to be true. Caveat: the @TeX{} +implementation reports internal @TeX{} commands, in addition to all +the Texinfo commands, as being ``defined''; the @code{makeinfo} +implementation is reliable in this regard, however. + +@pindex @file{NEWS} file for Texinfo +You can check the @file{NEWS} file in the Texinfo source distribution +and linked from the Texinfo home page +(@url{http://www.gnu.org/software/texinfo}) to see when a particular +command was added. + +@vindex txicommandconditionals +These command-checking conditionals themselves were added in +Texinfo@tie{}5.0, released in 2013---decades after Texinfo's +inception. In order to test if they themselves are available, +the predefined flag @code{txicommandconditionals} can be tested, like +this: + +@example +@@ifset txicommandconditionals +@@ifcommandnotdefined foobarnode +(Good, @@samp@{@@@@foobarnode@} is not defined.) +@@end ifcommandnotdefined +@@end ifset +@end example + +Since flags (see the previous section) were added early in the +existence of Texinfo, there is no problem with assuming they are +available. + +We recommend avoiding these tests whenever possible---which is usually +the case. For many software packages, it is reasonable for all +developers to have a given version of Texinfo (or newer) installed, +and thus no reason to worry about older versions. (It is +straightforward for anyone to download and install the Texinfo source; +it does not have any problematic dependencies.) + +The issue of Texinfo versions does not generally arise for end-users. +With properly distributed packages, users need not process the Texinfo +manual simply to build and install the package; they can use +preformatted Info (or other) output files. This is desirable in +general, to avoid unnecessary dependencies between packages +(@pxref{Releases,,, standards, GNU Coding Standards}). + + +@node Conditional Nesting +@section Conditional Nesting +@cindex Conditionals, nested +@cindex Nesting conditionals + +Conditionals can be nested; however, the details are a little tricky. +The difficulty comes with failing conditionals, such as +@code{@@ifhtml} when HTML is not being produced, where the included +text is to be ignored. However, it is not to be @emph{completely} +ignored, since it is useful to have one @code{@@ifset} inside another, +for example---that is a way to include text only if two conditions are +met. Here's an example: + +@example +@@ifset somevar +@@ifset anothervar +Both somevar and anothervar are set. +@@end ifset +@@ifclear anothervar +Somevar is set, anothervar is not. +@@end ifclear +@@end ifset +@end example + +Technically, Texinfo requires that for a failing conditional, the +ignored text must be properly nested with respect to that failing +conditional. Unfortunately, it's not always feasible to check that +@emph{all} conditionals are properly nested, because then the +processors could have to fully interpret the ignored text, which +defeats the purpose of the command. Here's an example illustrating +these rules: + +@example +@@ifset a +@@ifset b +@@ifclear ok - ok, ignored +@@end junky - ok, ignored +@@end ifset +@@c WRONG - missing @@end ifset. +@end example + +Finally, as mentioned above, all conditional commands must be on lines +by themselves, with no text (even spaces) before or after. Otherwise, +the processors cannot reliably determine which commands to consider +for nesting purposes. + + +@node Defining New Texinfo Commands +@chapter Defining New Texinfo Commands + +@cindex Macros +@cindex Defining new Texinfo commands +@cindex New Texinfo commands, defining +@cindex Texinfo commands, defining new +@cindex User-defined Texinfo commands + +Texinfo provides several ways to define new commands (in all cases, +it's not recommended to try redefining existing commands): + +@itemize @bullet +@item +A Texinfo @dfn{macro} allows you to define a new Texinfo command as any +sequence of text and/or existing commands (including other macros). The +macro can have any number of @dfn{parameters}---text you supply each +time you use the macro. + +Incidentally, these macros have nothing to do with the @code{@@defmac} +command, which is for documenting macros in the subject area of the +manual (@pxref{Def Cmd Template}). + +@item +@samp{@@alias} is a convenient way to define a new name for an existing +command. + +@item +@samp{@@definfoenclose} allows you to define new commands with +customized output for all non-@TeX{} output formats. + +@end itemize + +Most generally of all (not just for defining new commands), it is +possible to invoke any external macro processor and have Texinfo +recognize so-called @code{#line} directives for error reporting. + +If you want to do simple text substitution, @code{@@set} and +@code{@@value} is the simplest approach (@pxref{@code{@@set @@clear +@@value}}). + +@menu +* Defining Macros:: Defining and undefining new commands. +* Invoking Macros:: Using a macro, once you've defined it. +* Macro Details:: Limitations of Texinfo macros. +* @code{@@alias}:: Command aliases. +* @code{@@definfoenclose}:: Customized highlighting. +* External Macro Processors:: @code{#line} directives. +@end menu + + +@node Defining Macros +@section Defining Macros +@cindex Defining macros +@cindex Macro definitions, Texinfo + +@findex macro +You use the Texinfo @code{@@macro} command to define a macro, like this: + +@example +@@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@} +@var{text} @dots{} \@var{param1}\ @dots{} +@@end macro +@end example + +The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to +arguments supplied when the macro is subsequently used in the document +(described in the next section). + +@cindex Macro names, valid characters in +@cindex Names of macros, valid characters of +For a macro to work consistently with @TeX{}, @var{macroname} must +consist entirely of letters: no digits, hyphens, underscores, or other +special characters. So, we recommend using only letters. However, +@command{makeinfo} will accept anything consisting of alphanumerics, +and (except as the first character) @samp{-}. The @samp{_} character +is excluded so that macros can be called inside @code{@@math} without +a following space (@pxref{Inserting Math}). + +If a macro needs no parameters, you can define it either with an empty +list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro +foo}). + +@cindex Body of a macro +The definition or @dfn{body} of the macro can contain most Texinfo +commands, including macro invocations. However, a macro definition +that defines another macro does not work in @TeX{} due to limitations +in the design of @code{@@macro}. + +@cindex Parameters to macros +In the macro body, instances of a parameter name surrounded by +backslashes, as in @samp{\@var{param1}\} in the example above, are +replaced by the corresponding argument from the macro invocation. You +can use parameter names any number of times in the body, including zero. + +@cindex Backslash in macros +To get a single @samp{\} in the macro expansion, use @samp{\\}. Any +other use of @samp{\} in the body yields a warning. + +@cindex Spaces in macros +@cindex Whitespace in macros +The newline characters after the @code{@@macro} line and before the +@code{@@end macro} line are ignored, that is, not included in the +macro body. All other whitespace is treated according to the usual +Texinfo rules. + +@cindex Recursive macro invocations +@findex rmacro +To allow a macro to be used recursively, that is, in an argument to a +call to itself, you must define it with @samp{@@rmacro}, like this: + +@example +@@rmacro rmac @{arg@} +a\arg\b +@@end rmacro +@dots{} +@@rmac@{1@@rmac@{text@}2@} +@end example + +This produces the output `a1atextb2b'. With @samp{@@macro} instead of +@samp{@@rmacro}, an error message is given. + +@findex unmacro +@cindex Macros, undefining +@cindex Undefining macros +You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}. +It is not an error to undefine a macro that is already undefined. +For example: + +@example +@@unmacro foo +@end example + + +@node Invoking Macros +@section Invoking Macros + +@cindex Invoking macros +@cindex Expanding macros +@cindex Running macros +@cindex Macro invocation + +After a macro is defined (see the previous section), you can +@dfn{invoke} (use) it in your document like this: + +@example +@@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@} +@end example + +@noindent and the result will be more or less as if you typed the body of +@var{macroname} at that spot. For example: + +@example +@@macro foo @{p, q@} +Together: \p\ & \q\. +@@end macro +@@foo@{a, b@} +@end example + +@noindent produces: + +@display +Together: a & b. +@end display + +@cindex Backslash, and macros +Thus, the arguments and parameters are separated by commas and +delimited by braces; any whitespace after (but not before) a comma is +ignored. The braces are required in the invocation even when the +macro takes no arguments, consistent with other Texinfo commands. For +example: + +@example +@@macro argless @{@} +No arguments here. +@@end macro +@@argless@{@} +@end example + +@noindent produces: + +@display +No arguments here. +@end display + +@cindex Comma, in macro arguments +Passing macro arguments containing commas requires care, since +commas also separate the arguments. To include a comma character in +an argument, the most reliable method is to use the @code{@@comma@{@}} +command. For @code{makeinfo}, you can also prepend a backslash +character, as in @samp{\,}, but this does not work with @TeX{}. + +@cindex Automatic quoting of commas for some macros +@cindex Quoting, automatic for some macros +It's not always necessary to worry about commas. To facilitate use of +macros, @command{makeinfo} implements two rules for @dfn{automatic +quoting} in some circumstances: + +@enumerate 1 +@item If a macro takes only one argument, all commas in its invocation +are quoted by default. For example: + +@example +@group +@@macro TRYME@{text@} +@@strong@{TRYME: \text\@} +@@end macro + +@@TRYME@{A nice feature, though it can be dangerous.@} +@end group +@end example + +@noindent +will produce the following output + +@example +@strong{TRYME: A nice feature, though it can be dangerous.} +@end example + +And indeed, it can. Namely, @command{makeinfo} does not control the +number of arguments passed to one-argument macros, so be careful when +you invoke them. + +@item If a macro invocation includes another command (including a +recursive invocation of itself), any commas in the nested command +invocation(s) are quoted by default. For example, in + +@example +@@say@{@@strong@{Yes, I do@}, person one@} +@end example + +the comma after @samp{Yes} is implicitly quoted. Here's another +example, with a recursive macro: + +@example +@group +@@rmacro cat@{a,b@} +\a\\b\ +@@end rmacro + +@@cat@{@@cat@{foo, bar@}, baz@} +@end group +@end example + +@noindent +will produce the string @samp{foobarbaz}. + +@item Otherwise, a comma should be explicitly quoted, as above, for it +to be treated as a part of an argument. +@end enumerate + +@cindex Backslash, in macro arguments +@cindex Braces, in macro arguments +The backslash itself can be quoted in macro arguments with another +backslash. For example: + +@example +@@@var{macname} @{\\bleh@} +@end example + +@noindent +will pass the argument @samp{\bleh} to @var{macname}. + +@command{makeinfo} also recognizes @samp{\@{} and @samp{\@}} sequences +for curly braces, but these are not recognized by the implementation in +@TeX{}. There should, however, rarely be a need for these, as they are +only needed when a macro argument contains unbalanced braces. + +If a macro is defined to take exactly one argument, it can be +invoked without any braces, taking all of the line after the macro name +as the argument. For example: + +@example +@@macro bar @{p@} +Twice: \p\ & \p\. +@@end macro +@@bar aah +@end example + +@noindent produces: + +@display +Twice: aah & aah. +@end display + +@noindent +In these arguments, there is no escaping of special characters, so each +@samp{\} stands for itself. + +If a macro is defined to take more than one argument, but is called +with only one (in braces), the remaining arguments are set to the +empty string, and no error is given. For example: + +@example +@@macro addtwo @{p, q@} +Both: \p\\q\. +@@end macro +@@addtwo@{a@} +@end example + +@noindent produces simply: + +@display +Both: a. +@end display + + +@node Macro Details +@section Macro Details and Caveats +@cindex Macro details +@cindex Details of macro usage +@cindex Caveats for macro usage + +@cindex Macro expansion, contexts for +@cindex Expansion of macros, contexts for +By design, macro expansion does not happen in the following contexts +in @command{makeinfo}: + +@itemize @bullet +@item @code{@@macro} and @code{@@unmacro} lines; + +@item @code{@@if...} lines, including @code{@@ifset} and similar; + +@item @code{@@set}, @code{@@clear}, @code{@@value}; + +@item @code{@@clickstyle} lines; + +@item @code{@@end} lines. +@end itemize + +@noindent Unfortunately, @TeX{} may do some expansion in these situations, +possibly yielding errors. + +Also, quite a few macro-related constructs cause problems with @TeX{}; +some of the caveats are listed below. Thus, if you get macro-related +errors when producing the printed version of a manual, you might try +expanding the macros with @command{makeinfo} by invoking +@command{texi2dvi} with the @samp{-E} option (@pxref{Format with +@command{texi2dvi}}). Or, more reliably, eschew Texinfo macros altogether +and use a language designed for macro processing, such as M4 +(@pxref{External Macro Processors}). + +@itemize @bullet +@item +As mentioned earlier, macro names must consist entirely of letters. + +@item +It is not advisable to redefine any @TeX{} primitive, plain, or +Texinfo command name as a macro. Unfortunately this is a large and +open-ended set of names, and the possible resulting errors are +unpredictable. + +@item +Arguments to macros taking more than one argument cannot cross lines. + +@item +Macros containing a command which must be on a line by itself, such as +a conditional, cannot be invoked in the middle of a line. Similarly, +macros containing line-oriented commands or text, such as +@code{@@example} environments, may behave unpredictably in @TeX{}. + +@item +If you have problems using conditionals within a macro, an alternative +is to use separate macro definitions inside conditional blocks. For +example, instead of + +@example +@@macro Mac +@@iftex +text for TeX output +@@end iftex +@@ifnottex +text for not TeX output +@@end ifnottex +@@end macro +@end example + +@noindent you can do the following instead: + +@example +@@iftex +@@macro Mac +text for TeX output +@@end macro +@@end iftex + +@@ifnottex +@@macro Mac +text for not TeX output +@@end macro +@@end ifnottex +@end example + +@item +Texinfo commands in the expansion of a macro in the text of an index +entry may end up being typeset as literal text (including an ``@@'' +sign), instead of being interpreted with their intended meaning. + +@item +White space is ignored at the beginnings of lines. + +@item +Macros can't be reliably used in the argument to accent commands +(@pxref{Inserting Accents}). + +@item +The backslash escape for commas in macro arguments does not work; +@code{@@comma@{@}} must be used. + +@item +Likewise, if you want to pass an argument with the Texinfo command +@code{@@,} (to produce a cedilla, see @ref{Inserting Accents}), you have +to use @code{@@value} or another work-around. Otherwise, the comma +may be taken as separating the arguments. For example, + +@example +@@macro mactwo@{argfirst, argsecond@} +\argfirst\+\argsecond\. +@@end macro +@@set fc Fran@@,cois +@@mactwo@{@@value@{fc@},@} +@end example + +@noindent produces: + +@display +Fran@,cois+. +@end display + +@c currently @mactwo{Fran@,cois} works in TeX, but @mactwo{Franc@\,cois} +@c works in makeinfo. better to avoid commas altogether using this trick. +@c an alternative to @, could be invented if needed. + +@item +Ending a macro body with @samp{@@c} may cause text following the macro +invocation to be ignored as a comment in @command{makeinfo}. This is +not the case when processing with @TeX{}. This was often done +to ``comment out'' an unwanted newline at the end of a macro body, but +this is not necessary any more, as the final newline before @samp{@@end +macro} is not included in the macro body anyway. + +@item +In general, you can't arbitrarily substitute a macro (or +@code{@@value}) call for Texinfo command arguments, even when the text +is the same. Texinfo is not M4 (or even plain @TeX{}). It might work +with some commands, it fails with others. Best not to do it at all. +For instance, this fails: + +@example +@@macro offmacro +off +@@end macro +@@headings @@offmacro +@end example + +@noindent +This looks equivalent to @code{@@headings off}, but for @TeX{}nical +reasons, it fails with a mysterious error message (namely, +@samp{Paragraph ended before @@headings was complete}). + +@item +Macros cannot define macros in the natural way. To do this, you must +use conditionals and raw @TeX{}. For example: + +@example +@@ifnottex +@@macro ctor @{name, arg@} +@@macro \name\ +something involving \arg\ somehow +@@end macro +@@end macro +@@end ifnottex +@@tex +\gdef\ctor#1@{\ctorx#1,@} +\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@} +@@end tex +@end example +@end itemize + +The @command{makeinfo} implementation also has the following +limitations (by design): + +@itemize +@item +@code{@@verbatim} and macros do not mix; for instance, you can't start +a verbatim block inside a macro and end it outside +(@pxref{@code{@@verbatim}}). Starting any environment inside a macro +and ending it outside may or may not work, for that matter. + +@item +Macros that completely define macros are ok, but it's not possible to +have incompletely nested macro definitions. That is, @code{@@macro} +and @code{@@end macro} (likewise for @code{@@rmacro}) must be +correctly paired. For example, you cannot start a macro definition +within a macro, and then end that nested definition outside the macro. +@end itemize + +In the @code{makeinfo} implementation before Texinfo 5.0, ends of +lines from expansion of a @code{@@macro} definition did not end an +@@-command line-delimited argument (@code{@@chapter}, @code{@@center}, +etc.). This is no longer the case. For example: + +@example +@@macro twolines@{@} +aaa +bbb +@@end macro +@@center @@twolines@{@} +@end example + +In the current @code{makeinfo}, this is equivalent to: + +@example +@@center aaa +bbb +@end example + +@noindent with just @samp{aaa} as the argument to @code{@@center}. In +the earlier implementation, it would have been parsed as this: + +@example +@@center aaa bbb +@end example + + +@node @code{@@alias} +@section @samp{@@alias @var{new}=@var{existing}} + +@anchor{alias}@c old name +@cindex Aliases, command +@cindex Command aliases +@findex alias + +The @samp{@@alias} command defines a new command to be just like an +existing one. This is useful for defining additional markup names, +thus preserving additional semantic information in the input even +though the output result may be the same. + +Write the @samp{@@alias} command on a line by itself, followed by the +new command name, an equals sign, and the existing command name. +Whitespace around the equals sign is optional and ignored if present. +Thus: + +@example +@@alias @var{new} = @var{existing} +@end example + +For example, if your document contains citations for both books and +some other media (movies, for example), you might like to define a +macro @code{@@moviecite@{@}} that does the same thing as an ordinary +@code{@@cite@{@}} but conveys the extra semantic information as well. +You'd do this as follows: + +@example +@@alias moviecite = cite +@end example + +Macros do not always have the same effect as aliases, due to vagaries +of argument parsing. Also, aliases are much simpler to define than +macros. So the command is not redundant. + +Unfortunately, it's not possible to alias Texinfo environments; for +example, @code{@@alias lang=example} is an error. + +Aliases must not be recursive, directly or indirectly. + +It is not advisable to redefine any @TeX{} primitive, plain @TeX{}, or +Texinfo command name as an alias. Unfortunately this is a very large +set of names, and the possible resulting errors from @TeX{} are +unpredictable. + +@command{makeinfo} will accept the same identifiers for aliases as it +does for macro names, that is, alphanumerics and (except as the first +character) @samp{-}. + + +@node @code{@@definfoenclose} +@section @code{@@definfoenclose}: Customized Highlighting + +@anchor{definfoenclose}@c old name +@cindex Highlighting, customized +@cindex Customized highlighting +@findex definfoenclose + +An @code{@@definfoenclose} command may be used to define a +highlighting command for all the non-@TeX{} output formats. A command +defined using @code{@@definfoenclose} marks text by enclosing it in +strings that precede and follow the text. You can use this to get +closer control of your output. + +Presumably, if you define a command with @code{@@definfoenclose}, you +will create a corresponding command for @TeX{}, either in +@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} or +@samp{@@tex} in your document. + +Write a @code{@@definfoenclose} command at the beginning of a line +followed by three comma-separated arguments. The first argument to +@code{@@definfoenclose} is the @@-command name (without the +@code{@@}); the second argument is the start delimiter string; and the +third argument is the end delimiter string. The latter two arguments +enclose the highlighted text in the output. + +A delimiter string may contain spaces. Neither the start nor end +delimiter is required. If you do not want a start delimiter but do +want an end delimiter, you must follow the command name with two +commas in a row; otherwise, the end delimiter string you intended will +naturally be (mis)interpreted as the start delimiter string. + +If you do a @code{@@definfoenclose} on the name of a predefined +command (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or +@code{@@i}), the enclosure definition will override the built-in +definition. We don't recommend this. + +An enclosure command defined this way takes one argument in braces, +since it is intended for new markup commands (@pxref{Marking Text}). + +@findex phoo +For example, you can write: + +@example +@@definfoenclose phoo,//,\\ +@end example + +@noindent +near the beginning of a Texinfo file to define @code{@@phoo} as an Info +formatting command that inserts `//' before and `\\' after the argument +to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you +want `//bar\\' highlighted in Info. + +For @TeX{} formatting, you could write + +@example +@@iftex +@@global@@let@@phoo=@@i +@@end iftex +@end example + +@noindent +to define @code{@@phoo} as a command that causes @TeX{} to typeset the +argument to @code{@@phoo} in italics. + +Each definition applies to its own formatter: one for @TeX{}, the +other for everything else. The raw @TeX{} commands need to be in +@samp{@@iftex}. @code{@@definfoenclose} command need not be within +@samp{@@ifinfo}, unless you want to use different definitions for +different output formats. + +@findex headword +Here is another example: write + +@example +@@definfoenclose headword, , : +@end example + +@noindent +near the beginning of the file, to define @code{@@headword} as an Info +formatting command that inserts nothing before and a colon after the +argument to @code{@@headword}. + +@samp{@@definfoenclose} definitions must not be recursive, directly or +indirectly. + + +@node External Macro Processors +@section External Macro Processors: Line Directives +@cindex External macro processors +@cindex Macro processors, external + +Texinfo macros (and its other text substitution facilities) work fine +in straightforward cases. If your document needs unusually complex +processing, however, their fragility and limitations can be a problem. +In this case, you may want to use a different macro processor +altogether, such as M4 (@pxref{Top,,, m4, M4}) or CPP (@pxref{Top,,, +cpp, The C Preprocessor}). + +With one exception, Texinfo does not need to know whether its input is +``original'' source or preprocessed from some other source file. +Therefore, you can arrange your build system to invoke whatever +programs you like to handle macro expansion or other preprocessing +needs. Texinfo does not offer built-in support for any particular +preprocessor, since no one program seemed likely to suffice for the +requirements of all documents. + +@cindex Line numbers, in error messages +@cindex Error messages, line numbers in +The one exception is line numbers in error messages. In that case, +the line number should refer to the original source file, whatever it +may be. There's a well-known mechanism for this: the so-called +@samp{#line} directive. Texinfo supports this. + +@menu +* @samp{#line} Directive:: +* TeX: @samp{#line} and @TeX{}. +* Syntax: @samp{#line} Syntax Details. +@end menu + + +@node @samp{#line} Directive +@subsection @samp{#line} Directive + +@cindex @samp{#line} directive + +An input line such as this: + +@example +@hashchar{}line 100 "foo.ptexi" +@end example + +@noindent indicates that the next line was line 100 of the file +@file{foo.ptexi}, and so that's what an error message should refer to. +Both M4 (@pxref{Preprocessor features,,, m4, GNU M4}) and CPP +(@pxref{Line Control,,, cpp, The C Preprocessor}, and +@ref{Preprocessor Output,,, cpp, The C Preprocessor}) can generate +such lines. + +@vindex CPP_LINE_DIRECTIVES +The @command{makeinfo} program recognizes these lines by default, +except within @code{@@verbatim} blocks (@pxref{@code{@@verbatim}}). +Their recognition can be turned off completely with +@code{CPP_LINE_DIRECTIVES} (@pxref{Other Customization Variables}), +though there is normally no reason to do so. + +For those few programs (M4, CPP, Texinfo) which need to document +@samp{#line} directives and therefore have examples which would +otherwise match the pattern, the command @code{@@hashchar@{@}} can be +used (@pxref{Inserting a Hashsign}). The example line above looks +like this in the source for this manual: + +@example +@@hashchar@{@}line 100 "foo.ptexi" +@end example + +The @code{@@hashchar} command was added to Texinfo in 2013. If you +don't want to rely on it, you can also use @code{@@set} and +@code{@@value} to insert the literal @samp{#}: + +@example +@@set hash # +@@value@{hash@}line 1 "example.c" +@end example + +Or, if suitable, a @code{@@verbatim} environment can be used instead +of @code{@@example}. As mentioned above, @code{#line}-recognition is +disabled inside verbatim blocks. + + +@node @samp{#line} and @TeX{} +@subsection @samp{#line} and @TeX{} + +@cindex @TeX{} and @samp{#line} directives +@cindex @samp{#line} directives, not processing with @TeX{} + +As mentioned, @command{makeinfo} recognizes the @samp{#line} +directives described in the previous section. However, +@file{texinfo.tex} does not and cannot. Therefore, such a line will +be incorrectly typeset verbatim if @TeX{} sees it. The solution is to +use @command{makeinfo}'s macro expansion options before running +@TeX{}. There are three approaches: + +@itemize @bullet +@item +If you run @command{texi2dvi} or its variants (@pxref{Format with +@command{texi2dvi}}), you can pass @option{-E} and @command{texi2dvi} +will run @command{makeinfo} first to expand macros and eliminate +@samp{#line}. + +@item +If you run @command{makeinfo} or its variants (@pxref{Generic +Translator @command{texi2any}}), you can specify @option{--no-ifinfo +--iftex -E somefile.out}, and then give @file{somefile.out} to +@code{texi2dvi} in a separate command. + +@item +Or you can run @option{makeinfo --dvi --Xopt -E}. (Or @option{--pdf} +instead of @option{--dvi}.) @command{makeinfo} will then call +@command{texi2dvi -E}. +@end itemize + +@findex errormsg@r{, and line numbers in @TeX{}} +One last caveat regarding use with @TeX{}: since the @code{#line} +directives are not recognized, the line numbers emitted by the +@code{@@errormsg@{@}} command (@pxref{Conditional Commands}), or by +@TeX{} itself, are the (incorrect) line numbers from the derived file +which @TeX{} is reading, rather than the preprocessor-specified line +numbers. This is another example of why we recommend running +@command{makeinfo} for the best diagnostics (@pxref{@command{makeinfo} +Advantages}). + + +@node @samp{#line} Syntax Details +@subsection @samp{#line} Syntax Details + +@cindex @samp{#line} syntax details +@cindex Syntax details, @samp{#line} +@cindex Regular expression, for @samp{#line} + +Syntax details for the @samp{#line} directive: the @samp{#} character +can be preceded or followed by whitespace, the word @samp{line} is +optional, and the file name can be followed by a whitespace-separated +list of integers (these are so-called ``flags'' output by CPP in some +cases). For those who like to know the gory details, the actual +(Perl) regular expression which is matched is this: + +@example +/^\s*#\s*(line)? (\d+)(( "([^"]+)")(\s+\d+)*)?\s*$/ +@end example + +As far as we've been able to tell, the trailing integer flags only +occur in conjunction with a filename, so that is reflected in the +regular expression. + +As an example, the following is a syntactically valid @samp{#line} +directive, meaning line 1 of @file{/usr/include/stdio.h}: + +@example +@hashchar{} 1 "/usr/include/stdio.h" 2 3 4 +@end example + +Unfortunately, the quoted filename (@samp{"..."}) has to be optional, +because M4 (especially) can often generate @samp{#line} directives +within a single file. Since the @samp{line} is also optional, the +result is that lines might match which you wouldn't expect, e.g., + +@example +@hashchar{} 1 +@end example + +The possible solutions are described above (@pxref{@samp{#line} Directive}). + + +@node Include Files +@chapter Include Files + +@cindex Include files + +When a Texinfo processor sees an @code{@@include} command in a Texinfo +file, it processes the contents of the file named by the +@code{@@include} and incorporates them into the output files being +created. Include files thus let you keep a single large document as a +collection of conveniently small parts. + +@menu +* Using Include Files:: How to use the @code{@@include} command. +* @code{texinfo-multiple-files-update}:: How to create and update nodes and + menus when using included files. +* Include Files Requirements:: @code{texinfo-multiple-files-update} needs. +* Sample Include File:: A sample outer file with included files + within it; and a sample included file. +* @code{@@verbatiminclude}:: Including a file verbatim. +* Include Files Evolution:: How use of the @code{@@include} command + has changed over time. +@end menu + + +@node Using Include Files +@section How to Use Include Files + +@findex include + +To include another file within a Texinfo file, write the +@code{@@include} command at the beginning of a line and follow it on +the same line by the name of a file to be included. For example: + +@example +@@include buffers.texi +@end example + +@@-commands are expanded in file names. The one most likely to be +useful is @code{@@value} (@pxref{@code{@@set @@value}}), and even then +only in complicated situations. + +An included file should simply be a segment of text that you expect to +be included as is into the overall or @dfn{outer} Texinfo file; it +should not contain the standard beginning and end parts of a Texinfo +file. In particular, you should not start an included file with a +line saying @samp{\input texinfo}; if you do, that text is inserted +into the output file literally. Likewise, you should not end an +included file with a @code{@@bye} command; nothing after @code{@@bye} +is formatted. + +In the long-ago past, you were required to write an +@code{@@setfilename} line at the beginning of an included file, but no +longer. Now, it does not matter whether you write such a line. If an +@code{@@setfilename} line exists in an included file, it is ignored. + + +@node @code{texinfo-multiple-files-update} +@section @code{texinfo-multiple-files-update} + +@findex texinfo-multiple-files-update + +GNU Emacs Texinfo mode provides the +@code{texinfo-multiple-files-update} command. This command creates or +updates `Next', `Previous', and `Up' pointers of included files as +well as those in the outer or overall Texinfo file, and it creates or +updates a main menu in the outer file. Depending on whether you call +it with optional arguments, the command updates only the pointers in +the first @code{@@node} line of the included files or all of them: + +@table @kbd +@item M-x texinfo-multiple-files-update +Called without any arguments: + +@itemize @minus +@item +Create or update the `Next', `Previous', and `Up' pointers of the +first @code{@@node} line in each file included in an outer or overall +Texinfo file. + +@item +Create or update the `Top' level node pointers of the outer or +overall file. + +@item +Create or update a main menu in the outer file. +@end itemize + +@item C-u M-x texinfo-multiple-files-update +Called with @kbd{C-u} as a prefix argument: + +@itemize @minus{} +@item +Create or update pointers in the first @code{@@node} line in each +included file. + +@item +Create or update the `Top' level node pointers of the outer file. + +@item +Create and insert a master menu in the outer file. The master menu +is made from all the menus in all the included files. +@end itemize + +@item C-u 8 M-x texinfo-multiple-files-update +Called with a numeric prefix argument, such as @kbd{C-u 8}: + +@itemize @minus +@item +Create or update @emph{all} the `Next', `Previous', and `Up' pointers +of all the included files. + +@item +Create or update @emph{all} the menus of all the included +files. + +@item +Create or update the `Top' level node pointers of the outer or +overall file. + +@item +And then create a master menu in the outer file. This is similar to +invoking @code{texinfo-master-menu} with an argument when you are +working with just one file. +@end itemize +@end table + +Note the use of the prefix argument in interactive use: with a regular +prefix argument, just @w{@kbd{C-u}}, the +@code{texinfo-multiple-files-update} command inserts a master menu; +with a numeric prefix argument, such as @kbd{C-u 8}, the command +updates @emph{every} pointer and menu in @emph{all} the files and +then inserts a master menu. + + +@node Include Files Requirements +@section Include Files Requirements +@cindex Include files requirements +@cindex Requirements for include files + +If you plan to use the @code{texinfo-multiple-files-update} command, +the outer Texinfo file that lists included files within it should +contain nothing but the beginning and end parts of a Texinfo file, and +a number of @code{@@include} commands listing the included files. It +should not even include indices, which should be listed in an included +file of their own. + +Moreover, each of the included files must contain exactly one highest +level node (conventionally, @code{@@chapter} or equivalent), +and this node must be the first node in the included file. +Furthermore, each of these highest level nodes in each included file +must be at the same hierarchical level in the file structure. +Usually, each is a @code{@@chapter}, an @code{@@appendix}, or an +@code{@@unnumbered} node. Thus, normally, each included file contains +one, and only one, chapter or equivalent-level node. + +The outer file should contain only @emph{one} node, the `Top' node. It +should @emph{not} contain any nodes besides the single `Top' node. The +@code{texinfo-multiple-files-update} command will not process +them. + + +@node Sample Include File +@section Sample File with @code{@@include} +@cindex Sample @code{@@include} file +@cindex Include file sample +@cindex @code{@@include} file sample + +Here is an example of an outer Texinfo file with @code{@@include} files +within it before running @code{texinfo-multiple-files-update}, which +would insert a main or master menu: + +@example +@group +\input texinfo @@c -*-texinfo-*- +@c %**start of header +@@settitle Include Example +@c %**end of header +@end group + +... @xref{Sample Texinfo Files}, for +examples of the rest of the frontmatter ... + +@group +@@ifnottex +@@node Top +@@top Include Example +@@end ifnottex +@end group + +@group +@@include foo.texinfo +@@include bar.texinfo +@@include concept-index.texinfo +@@bye +@end group +@end example + +An included file, such as @file{foo.texinfo}, might look like this: + +@example +@group +@@node First +@@chapter First Chapter + +Contents of first chapter @dots{} +@end group +@end example + +The full contents of @file{concept-index.texinfo} might be as simple as this: + +@example +@group +@@node Concept Index +@@unnumbered Concept Index + +@@printindex cp +@end group +@end example + +The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference +Manual} is named @file{elisp.texi}. This outer file contains a master +menu with 417 entries and a list of 41 @code{@@include} +files. + + +@node @code{@@verbatiminclude} +@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim + +@anchor{verbatiminclude}@c old name +@findex verbatiminclude +@cindex Verbatim, include file +@cindex Including a file verbatim + +You can include the exact contents of a file in the document with the +@code{@@verbatiminclude} command: + +@example +@@verbatiminclude @var{filename} +@end example + +The contents of @var{filename} is printed in a verbatim environment +(@pxref{@code{@@verbatim}}). Generally, the file is printed exactly +as it is, with all special characters and white space retained. No +indentation is added; if you want indentation, enclose the +@code{@@verbatiminclude} within @code{@@example} +(@pxref{@code{@@example}}). + +The name of the file is taken literally, with a single exception: +@code{@@value@{@var{var}@}} references are expanded. This makes it +possible to include files in other directories within a distribution, +for instance: + +@example +@@verbatiminclude @@value@{top_srcdir@}/NEWS +@end example + +@noindent (You still have to get @code{top_srcdir} defined in the +first place.) + +For a method on printing the file contents in a smaller font size, see +the end of the section on @code{@@verbatim}. + + +@node Include Files Evolution +@section Evolution of Include Files + +When Info was first created, it was customary to create many small +Info files on one subject. Each Info file was formatted from its own +Texinfo source file. This custom meant that Emacs did not need to +make a large buffer to hold the whole of a large Info file when +someone wanted information; instead, Emacs allocated just enough +memory for the small Info file that contained the particular +information sought. This way, Emacs could avoid wasting memory. + +References from one file to another were made by referring to the file +name as well as the node name. (@xref{Other Info Files, , Referring to +Other Info Files}. Also, see @ref{Four and Five Arguments, , +@code{@@xref} with Four and Five Arguments}.) + +Include files were designed primarily as a way to create a single, +large printed manual out of several smaller Info files. In a printed +manual, all the references were within the same document, so @TeX{} +could automatically determine the references' page numbers. The Info +formatting commands used include files only for creating joint +indices; each of the individual Texinfo files had to be formatted for +Info individually. (Each, therefore, required its own +@code{@@setfilename} line.) + +However, because large Info files are now split automatically, it is +no longer necessary to keep them small. + +Nowadays, multiple Texinfo files are used mostly for large documents, +such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects +in which several different people write different sections of a +document simultaneously. + +In addition, the Info formatting commands have been extended to work +with the @code{@@include} command so as to create a single large Info +file that is split into smaller files if necessary. This means that +you can write menus and cross-references without naming the different +Texinfo files. + + +@node Hardcopy +@chapter Formatting and Printing Hardcopy +@cindex Format and print hardcopy +@cindex Printing hardcopy +@cindex Hardcopy, printing it +@cindex Making a printed manual +@cindex Sorting indices +@cindex Indices, sorting +@cindex @TeX{} index sorting + +Running the @command{texi2dvi} or @command{texi2pdf} command is the +simplest way to create printable output. These commands are installed +as part of the Texinfo package. + +In more detail, three major shell commands are used to print formatted +output from a Texinfo manual: one converts the Texinfo source into +something printable, a second sorts indices, and a third actually +prints the formatted document. When you use the shell commands, you +can either work directly in the operating system shell or work within +a shell inside GNU Emacs (or some other computing environment). + +If you are using GNU Emacs, you can use commands provided by Texinfo +mode instead of shell commands. In addition to the three commands to +format a file, sort the indices, and print the result, Texinfo mode +offers key bindings for commands to recenter the output buffer, show the +print queue, and delete a job from the print queue. + +Details are in the following sections. + +@menu +* Use @TeX{}:: Use @TeX{} to format for hardcopy. +* Format with @command{texi2dvi}:: The simplest way to format. +* Format with @command{tex}/@command{texindex}:: Formatting with explicit shell commands. +* Print with @command{lpr}:: How to print. +* Within Emacs:: How to format and print from an Emacs shell. +* Texinfo Mode Printing:: How to format and print in Texinfo mode. +* Compile-Command:: How to print using Emacs's compile command. +* Requirements Summary:: @TeX{} formatting requirements summary. +* Preparing for @TeX{}:: What to do before you use @TeX{}. +* Overfull hboxes:: What are and what to do with overfull hboxes. +* @code{@@smallbook}:: How to print small format books and manuals. +* A4 Paper:: How to print on A4 or A5 paper. +* @code{@@pagesizes}:: How to print with customized page sizes. +* Magnification:: How to print scaled up output. +* PDF Output:: Portable Document Format output. +* Obtaining @TeX{}:: How to obtain @TeX{}. +@end menu + + +@node Use @TeX{} +@section Use @TeX{} + +The typesetting program called @TeX{} is used to format a Texinfo +document for printable output. @TeX{} is a very powerful typesetting +program and, when used correctly, does an exceptionally good job. + +@xref{Obtaining @TeX{}}, for information on how to obtain @TeX{}. It +is not included in the Texinfo package, being a vast suite of software +in itself. + + +@node Format with @command{texi2dvi} +@section Format with @command{texi2dvi} + +@pindex texi2dvi @r{(shell script)} +@cindex DVI, output in + +The @code{texi2dvi} program takes care of all the steps for producing +a @TeX{} DVI file from a Texinfo document. Similarly, @code{texi2pdf} +produces a PDF file. + +To run @code{texi2dvi} or @code{texi2pdf} on an input file +@file{foo.texi}, do this (where @samp{prompt$ } is your shell prompt): + +@example +prompt$ @kbd{texi2dvi foo.texi} +prompt$ @kbd{texi2pdf foo.texi} +@end example + +As shown in this example, the input filenames to @code{texi2dvi} and +@code{texi2pdf} must include any extension, such as @samp{.texi}. +(Under MS-DOS and perhaps in other circumstances, you may need to run +@samp{sh texi2dvi foo.texi} instead of relying on the operating system +to invoke the shell on the @samp{texi2dvi} script.) + +For a list of all the options, run @samp{texi2dvi --help}. Some of the +options are discussed below. + +@opindex --pdf@r{, for @command{texi2dvi}} +@pindex pdftexi2dvi +With the @option{--pdf} option, @command{texi2dvi} produces PDF output +instead of DVI (@pxref{PDF Output}), by running @command{pdftex} +instead of @command{tex}. Alternatively, the command +@command{texi2pdf} is an abbreviation for running @samp{texi2dvi +--pdf}. The command @command{pdftexi2dvi} is also provided as a +convenience for AUC-@TeX{} (@pxref{Top,,, auctex, AUC-@TeX{}}), as it +prefers to merely prepend @samp{pdf} to DVI producing tools to have +PDF producing tools. + +@opindex --dvipdf@r{, for @command{texi2dvi}} +@pindex dvipdfmx +With the @option{--dvipdf} option, @command{texi2dvi} produces PDF +output by running @TeX{} and then a DVI-to-PDF program: if the +@env{DVIPDF} environment variable is set, that value is used, else the +first program extant among @code{dvipdfmx}, @code{dvipdfm}, +@code{dvipdf}, @code{dvi2pdf}, @code{dvitopdf}. This method generally +supports CJK typesetting better than @command{pdftex}. + +@opindex --ps@r{, for @command{texi2dvi}} +@pindex dvips +With the @option{--ps} option, @command{texi2dvi} produces PostScript +instead of DVI, by running @command{tex} and then @command{dvips} +(@pxref{Top,,, dvips, Dvips}). (Or the value of the @env{DVIPS} +environment variable, if set.) + +@opindex --language@r{, for @command{texi2dvi}} +@cindex @LaTeX{}, processing with @command{texi2dvi} +@command{texi2dvi} can also be used to process @LaTeX{} files. +Normally @command{texi2dvi} is able to guess the input file language +by its contents and file name extension; however, if it guesses wrong +you can explicitly specify the input language using +@option{--language=@var{lang}} command line option, where @var{lang} +is either @samp{latex} or @samp{texinfo}. + +@opindex --command@r{, for @command{texi2dvi}} +One useful option to @code{texi2dvi} is @samp{--command=@var{cmd}}. +This inserts @var{cmd} on a line by itself at the start of the file +in a temporary copy of the input file, before +running @TeX{}. With this, you can specify different printing +formats, such as @code{@@smallbook} (@pxref{@code{@@smallbook}}), +@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes} +(@pxref{@code{@@pagesizes}}), without actually changing the document +source. (You can also do this on a site-wide basis with +@file{texinfo.cnf}; @pxref{Preparing for @TeX{}}). + +The option @option{-E} (equivalently, @option{-e} and +@option{--expand}) does Texinfo macro expansion using +@command{makeinfo} instead of the @TeX{} implementation (@pxref{Macro +Details}). Each implementation has its own limitations and +advantages. If this option is used, no line in the source file +may begin with the string @code{@@c@tie{}_texi2dvi} or the +string @code{@@c@tie{}(_texi2dvi)}. + +@command{texi2dvi} takes the @option{--build=@var{mode}} option to +specify where the @TeX{} compilation takes place, and, as a +consequence, how auxiliary files are treated. The build mode +can also be set using the environment variable +@env{TEXI2DVI_BUILD_MODE}. The valid values for @var{mode} are: + +@table @samp +@item local + Compile in the current directory, leaving all the auxiliary + files around. This is the traditional TeX use. + +@item tidy + Compile in a local @code{*.t2d} directory, where the auxiliary files + are left. Output files are copied back to the original file. + + Using the @samp{tidy} mode brings several advantages: + @itemize - + @item the current directory is not cluttered with plethora of temporary files. + @item clutter can be even further reduced using @option{--build-dir=dir}: all + the @code{*.t2d} directories are stored there. + @item clutter can be reduced to zero using, e.g., + @option{--build-dir=/tmp/\$USER.t2d} or @option {--build-dir=\$HOME/.t2d}. + @item the output file is updated after every successful @TeX{} run, for + sake of concurrent visualization of the output. In a @samp{local} build + the viewer stops during the whole @TeX{} run. + @item if the compilation fails, the previous state of the output file + is preserved. + @item @acronym{PDF} and @acronym{DVI} compilation are kept in separate + subdirectories + preventing any possibility of auxiliary file incompatibility. + @end itemize + + On the other hand, because @samp{tidy} compilation takes place in another + directory, occasionally @TeX{} won't be able to find some files (e.g., when + using @code{\graphicspath}): in that case, use @option{-I} to specify the + additional directories to consider. + +@item clean + Same as @samp{tidy}, but remove the auxiliary directory afterwards. + Every compilation therefore requires the full cycle. +@end table + +@pindex etex +@pindex pdfetex +@command{texi2dvi} will use @command{etex} (or @command{pdfetex}) if +it is available, because it runs faster in some cases, and +provides additional tracing information when debugging +@file{texinfo.tex}. Nevertheless, this extended version of @TeX{} is +not required, and the DVI output is identical. +(These days, @command{pdftex} and @command{pdfetex} are exactly the +same, but we still run @command{pdfetex} to cater to ancient @TeX{} +installations.) + +@cindex filename recorder for @TeX{} +@cindex @samp{\openout} line in log file +@command{texi2dvi} attempts to detect auxiliary files output by @TeX{}, +either by using the @option{-recorder} option, or by scanning for +@samp{\openout} in the log file that a run of @TeX{} produces. You may +control how @command{texi2dvi} does this with the @env{TEXI2DVI_USE_RECORDER} +environment variable. Valid values are: + +@table @samp +@item yes +use the @option{-recorder} option, no checks. + +@item no +scan for @samp{\openout} in the log file, no checks. + +@item yesmaybe +check whether @option{-recorder} option is supported, and if yes +use it, otherwise check for tracing @samp{\openout} in the log file is +supported, and if yes use it, else it is an error. + +@item nomaybe +same as @samp{yesmaybe}, except that the @samp{\openout} trace in log +file is checked first. +@end table + +The default is @samp{nomaybe}. This environment variable is provided +for troubleshooting purposes, and may change or disappear in the future. + + +@node Format with @command{tex}/@command{texindex} +@section Format with @command{tex}/@command{texindex} + +@cindex Shell formatting with @code{tex} and @code{texindex} +@cindex Formatting with @code{tex} and @code{texindex} +@cindex DVI file + +You can do the basic formatting of a Texinfo file with the shell +command @code{tex} followed by the name of the Texinfo file. For +example: + +@example +tex foo.texi +@end example + +@noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary +files containing information for indices, cross-references, etc. The +DVI file (for @dfn{DeVice Independent} file) can be printed on +virtually any device, perhaps after a further conversion (see the +previous section). + +@pindex texindex +The @code{tex} formatting command itself does not sort the indices; it +writes an output file of unsorted index data. To generate a printed +index after running the @command{tex} command, you first need a sorted +index to work from. The @command{texindex} command sorts indices. +(@command{texi2dvi}, described in the previous section, runs +@command{tex} and @command{texindex} as necessary.) + +@anchor{Names of index files} +@cindex Names of index files +@cindex Index file names +@code{tex} outputs unsorted index files under names following a +standard convention: the name of your main input file with any +@samp{.texi} or similar extension replaced by the two letter index +name. For example, the raw index output files for the input file +@file{foo.texi} would be, by default, @file{foo.cp}, @file{foo.vr}, +@file{foo.fn}, @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those +are exactly the arguments to give to @code{texindex}. + +@need 1000 +@cindex Wildcards +@cindex Globbing +Instead of specifying all the unsorted index file names explicitly, +it's typical to use @samp{??} as shell wildcards and give the command +in this form: + +@example +texindex foo.?? +@end example + +@noindent +This command will run @code{texindex} on all the unsorted index files, +including any two letter indices that you have defined yourself using +@code{@@defindex} or @code{@@defcodeindex}. You can safely run +@samp{texindex foo.??} even if there are files with two letter +extensions that are not index files, such as @samp{foo.el}. The +@code{texindex} command reports but otherwise ignores such files. + +For each file specified, @code{texindex} generates a sorted index file +whose name is made by appending @samp{s} to the input file name; for +example, @file{foo.cps} is made from @file{foo.cp}. The +@code{@@printindex} command looks for a file with that name +(@pxref{Printing Indices & Menus}). @TeX{} does not read the raw +index output file, and @code{texindex} does not alter it. + +After you have sorted the indices, you need to rerun @code{tex} on the +Texinfo file. This regenerates the output file, this time with +up-to-date index entries. + +Finally, you may need to run @code{tex} one more time, to get the page +numbers in the cross-references correct. + +To summarize, this is a five step process. (Alternatively, it's a +one-step process: run @code{texi2dvi}; see the previous section.) + +@enumerate +@item +Run @code{tex} on your Texinfo file. This generates a DVI file (with +undefined cross-references and no indices), and the raw index files +(with two letter extensions). + +@item +Run @code{texindex} on the raw index files. This creates the +corresponding sorted index files (with three letter extensions). + +@item +Run @code{tex} again on your Texinfo file. This regenerates the DVI +file, this time with indices and defined cross-references, but with +page numbers for the cross-references from the previous run, generally +incorrect. + +@item +Sort the indices again, with @code{texindex}. + +@item +Run @code{tex} one last time. This time the correct page numbers are +written for the cross-references. +@end enumerate + +@menu +* Formatting Partial Documents:: +* Details of @command{texindex}:: +@end menu + +@node Formatting Partial Documents +@subsection Formatting Partial Documents + +@cindex Formatting partial documents +@cindex Partial documents, formatting +@cindex Chapters, formatting one at a time +@cindex Auxiliary files, omitting +@cindex Pointer validation, suppressing +@findex novalidate + +Sometimes you may wish to print a document while you know it is +incomplete, or to print just one chapter of a document. In such a +case, the usual auxiliary files that @TeX{} creates and warnings +@TeX{} gives about undefined cross-references are just nuisances. You +can avoid them with the @code{@@novalidate} command, which you must +give @emph{before} any sectioning or cross-reference commands. + +Thus, the beginning of your file would look approximately like this: + +@example +\input texinfo +@@novalidate +@dots{} +@end example + +@noindent @code{@@novalidate} also turns off validation in +@code{makeinfo}, just like its @code{--no-validate} option +(@pxref{Pointer Validation}). + +Furthermore, you need not run @code{texindex} each time after you run +@code{tex}. The @code{tex} formatting command simply uses whatever +sorted index files happen to exist from a previous use of +@code{texindex}. If those are out of date, that is usually ok while +you are creating or debugging a document. + + +@node Details of @command{texindex} +@subsection Details of @command{texindex} + +@cindex Braces, in index entries +In Texinfo version 6, released in 2015, the @command{texindex} program +was completely reimplemented. The principal functional difference is +that index entries beginning with a left brace or right brace +(@samp{@{} resp.@: @samp{@}}) can work properly. For example, these +simple index entries are processed correctly, including the ``index +initial'' shown in the index: + +@example +@@cindex @@@{ +@@cindex @@@} +... +@@printindex cp +@end example + + +@cindex Literate programming, with Texinfo and @code{awk} +@cindex Texinfo, and literate programming +@cindex Robbins, Arnold +@pindex texiwebjr +@pindex ti.twjr +Although not a matter of functionality, readers may be interested to +know that the new @command{texindex} is a literate program +(@url{http://en.wikipedia.org/wiki/Literate_programming}) using +Texinfo for documentation and (portable) @code{awk} for code. A +single source file, @file{texindex/ti.twjr} in this case, produces the +runnable program, a printable document, and an online document. + +The system is called TexiWeb Jr.@: and was created by Arnold +Robbins, who also wrote the new @command{texindex}. Not +coincidentally, he is also the long-time maintainer of @command{gawk} +(GNU Awk, @pxref{Top,,, gawk, The GNU Awk User's Guide}). The file +@file{texindex/Makefile.am} shows example usage of the system. + + +@node Print with @command{lpr} +@section Print with @command{lpr} from Shell + +@pindex lpr @r{(DVI print command)} + +The way to print a DVI file depends on your system installation. Two +common ones are @samp{dvips foo.dvi -o} to make a PostScript file +first and then print that, and @samp{lpr -d foo.dvi} to print a DVI +file directly. + +For example, the following commands will (probably) suffice to sort +the indices, format, and print this manual using the @code{texi2dvi} +shell script (@pxref{Format with @command{texi2dvi}}). + +@example +@group +texi2dvi texinfo.texi +dvips texinfo.dvi -o +lpr texinfo.ps +@end group +@end example + +Depending on the @code{lpr} setup on your machine, you might able to +combine the last two steps into @code{lpr -d texinfo.dvi}. + +@cindex PCL file, for printing +You can also generate a PDF file by running @code{texi2pdf} instead of +@code{texi2dvi}; a PDF is often directly printable. Or you can +generate a PCL file by using @code{dvilj} instead of @code{dvips}, if +you have a printer that prefers that format. + +@cindex Shell printing, on MS-DOS/MS-Windows +@cindex Printing DVI files, on MS-DOS/MS-Windows +@pindex lpr@r{-d, replacements on MS-DOS/MS-Windows} +@code{lpr} is a standard program on Unix systems, but it is usually +absent on MS-DOS/MS-Windows. If so, just create a PostScript or PDF +or PCL file, whatever is most convenient, and print that in the usual +way for your machine (e.g., by sending to the appropriate port, +usually @samp{PRN}). + + +@node Within Emacs +@section Printing From an Emacs Shell +@cindex Print, format from Emacs shell +@cindex Format, print from Emacs shell +@cindex Shell, format, print from +@cindex Emacs shell, format, print from +@cindex GNU Emacs shell, format, print from + +You can give formatting and printing commands from a shell within GNU +Emacs, just like any other shell command. To create a shell within +Emacs, type @kbd{M-x shell} (@pxref{Shell,,, emacs, The GNU Emacs +Manual}). In this shell, you can format and print the document. +@xref{Hardcopy, , Format and Print Hardcopy}, for details. + +You can switch to and from the shell buffer while @code{tex} is +running and do other editing. If you are formatting a long document +on a slow machine, this can be very convenient. + +For example, you can use @code{texi2dvi} from an Emacs shell. Here is +one way to use @code{texi2pdf} to format and print @cite{Using and +Porting GNU CC} from a shell within Emacs: + +@example +@group +texi2pdf gcc.texi +lpr gcc.pdf +@end group +@end example + +See the next section for more information about formatting +and printing in Texinfo mode. + + +@node Texinfo Mode Printing +@section Formatting and Printing in Texinfo Mode +@cindex Region printing in Texinfo mode +@cindex Format and print in Texinfo mode +@cindex Print and format in Texinfo mode + +Texinfo mode provides several predefined key commands for @TeX{} +formatting and printing. These include commands for sorting indices, +looking at the printer queue, killing the formatting job, and +recentering the display of the buffer in which the operations +occur. + +@table @kbd +@item C-c C-t C-b +@itemx M-x texinfo-tex-buffer +Run @code{texi2dvi} on the current buffer. + +@item C-c C-t C-r +@itemx M-x texinfo-tex-region +Run @TeX{} on the current region. + +@item C-c C-t C-i +@itemx M-x texinfo-texindex +Sort the indices of a Texinfo file formatted with +@code{texinfo-tex-region}. + +@item C-c C-t C-p +@itemx M-x texinfo-tex-print +Print a DVI file that was made with @code{texinfo-tex-region} or +@code{texinfo-tex-buffer}. + +@item C-c C-t C-q +@itemx M-x tex-show-print-queue +Show the print queue. + +@item C-c C-t C-d +@itemx M-x texinfo-delete-from-print-queue +Delete a job from the print queue; you will be prompted for the job +number shown by a preceding @kbd{C-c C-t C-q} command +(@code{texinfo-show-tex-print-queue}). + +@item C-c C-t C-k +@itemx M-x tex-kill-job +Kill the currently running @TeX{} job started by either +@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other +process running in the Texinfo shell buffer. + +@item C-c C-t C-x +@itemx M-x texinfo-quit-job +Quit a @TeX{} formatting job that has stopped because of an error by +sending an @key{x} to it. When you do this, @TeX{} preserves a record +of what it did in a @file{.log} file. + +@item C-c C-t C-l +@itemx M-x tex-recenter-output-buffer +Redisplay the shell buffer in which the @TeX{} printing and formatting +commands are run to show its most recent output. +@end table + +@need 1000 +Thus, the usual sequence of commands for formatting a buffer is as +follows (with comments to the right): + +@example +@group +C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.} +C-c C-t C-p @r{Print the DVI file.} +C-c C-t C-q @r{Display the printer queue.} +@end group +@end example + +The Texinfo mode @TeX{} formatting commands start a subshell in Emacs +called the @file{*tex-shell*}. The @code{texinfo-tex-command}, +@code{texinfo-texindex-command}, and @code{tex-dvi-print-command} +commands are all run in this shell. + +You can watch the commands operate in the @samp{*tex-shell*} buffer, +and you can switch to and from and use the @samp{*tex-shell*} buffer +as you would any other shell buffer. + +@need 1500 +The formatting and print commands depend on the values of several variables. +The default values are: + +@example +@group + @r{Variable} @r{Default value} + +texinfo-texi2dvi-command "texi2dvi" +texinfo-tex-command "tex" +texinfo-texindex-command "texindex" +texinfo-delete-from-print-queue-command "lprm" +texinfo-tex-trailer "@@bye" +tex-start-of-header "%**start" +tex-end-of-header "%**end" +tex-dvi-print-command "lpr -d" +tex-show-queue-command "lpq" +@end group +@end example + +You can change the values of these variables with the @kbd{M-x +set-variable} command (@pxref{Examining, , Examining and Setting +Variables, emacs, The GNU Emacs Manual}), or with your @file{.emacs} +initialization file (@pxref{Init File, , , emacs, The GNU Emacs +Manual}). + +@cindex Customize Emacs package (@t{Development/Docs/Texinfo}) +Beginning with version 20, GNU Emacs offers a user-friendly interface, +called @dfn{Customize}, for changing values of user-definable variables. +@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU +Emacs Manual}, for more details about this. The Texinfo variables can +be found in the @samp{Development/Docs/Texinfo} group, once you invoke +the @kbd{M-x customize} command. + + +@node Compile-Command +@section Using the Local Variables List +@cindex Local variables +@cindex Compile command for formatting +@cindex Format with the compile command + +Yet another way to apply the @TeX{} formatting command to a Texinfo file +is to put that command in a @dfn{local variables list} at the end of the +Texinfo file. You can then specify the @code{tex} or @code{texi2dvi} +commands as a @code{compile-command} and have Emacs run it by typing +@kbd{M-x compile}. This creates a special shell called the +@file{*compilation*} buffer in which Emacs runs the compile command. +For example, at the end of the @file{gdb.texi} file, after the +@code{@@bye}, you could put the following: + +@example +@group +Local Variables: +compile-command: "texi2dvi gdb.texi" +End: +@end group +@end example + +@noindent +This technique is most often used by programmers who also compile programs +this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}. + + +@node Requirements Summary +@section @TeX{} Formatting Requirements Summary +@cindex Requirements for formatting +@cindex Minimal requirements for formatting +@cindex Formatting requirements + +Every Texinfo file that is to be input to @TeX{} must begin with a +@code{\input} command: + +@example +\input texinfo +@end example + +@noindent +This instructs @TeX{} to load the macros it needs to process a Texinfo +file. + +Every Texinfo file must end with a line that terminates @TeX{}'s +processing and forces out unfinished pages: + +@example +@@bye +@end example + +Strictly speaking, these two lines are all a Texinfo file needs to be +processed successfully by @TeX{}. + +Usually, however, the beginning includes a @code{@@settitle} command +to define the title of the printed manual, a title page, a copyright +page, permissions, and a table of contents. Besides @code{@@bye}, the +end of a file usually includes indices. (Not to mention that most +manuals contain a body of text as well.) + +For more information, see: + +@itemize @bullet +@item @ref{@code{@@settitle}}. +@item @ref{@code{@@setchapternewpage}}. +@item @ref{Headings}. +@item @ref{Titlepage & Copyright Page}. +@item @ref{Printing Indices & Menus}. +@item @ref{Contents}. +@end itemize + + +@node Preparing for @TeX{} +@section Preparing for @TeX{} +@cindex Preparing for @TeX{} +@cindex @TeX{} input initialization +@cindex @sortas{profile init} @file{.profile} initialization file +@cindex @sortas{cshrc init} @file{.cshrc} initialization file +@cindex Initialization file for @TeX{} input + +@TeX{} needs to know where to find the @file{texinfo.tex} file that the +@samp{\input texinfo} command on the first line reads. The +@file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is +included in all standard GNU distributions. The latest version +released for general use is available +from the usual GNU servers and mirrors: + +@smalldisplay +@uref{http://ftp.gnu.org/gnu/texinfo/texinfo.tex} +@uref{http://ftpmirror.gnu.org/texinfo/texinfo.tex} +@end smalldisplay + +The latest development version is available from the Texinfo source +repository: +@smalldisplay +@uref{http://svn.savannah.gnu.org/viewvc/trunk/doc/texinfo.tex?root=texinfo&view=log} +@end smalldisplay + +@pindex texinfo.tex@r{, installing} +@file{texinfo.tex} is essentially a standalone file, and compatibility +is of utmost concern; so, if you need or want to try a newer version +than came with your system, it nearly always suffices to download it +and put it anywhere that @TeX{} will find it (first). You can replace +any existing @file{texinfo.tex} with a newer version (of course saving +the original in case of disaster). + +@pindex epsf.tex@r{, installing} +Also, you should install @file{epsf.tex}, if it is not already installed +from another distribution. More details are at the end of the description +of the @code{@@image} command (@pxref{Images}). + +@cindex European Computer Modern fonts, installing +@cindex EC fonts, installing +@cindex CM-Super fonts, installing +To use quotation marks other than those used in English, you'll need +to have the European Computer Modern fonts (e.g., @file{ecrm1000}) and +(for PDF output) CM-Super fonts (@pxref{Inserting Quotation Marks}). + +@pindex feymr10@r{, installing} +@cindex Euro font, installing +To use the @code{@@euro} command, you'll need the @samp{feym*} fonts +(e.g., @file{feymr10}). @xref{@code{@@euro}}. + +All of the above files (and a whole lot more) should be installed by +default in a reasonable @TeX{} installation. + +@pindex texinfo.cnf @r{installation} +@cindex Customizing of @TeX{} for Texinfo +@cindex Site-wide Texinfo configuration file +Optionally, you may create a file @file{texinfo.cnf} for site configuration. +This file is read by @TeX{} at the beginning of a Texinfo file. +You can put any commands you like there, according to local site-wide +conventions. They will be read by @TeX{} when processing any Texinfo +document. For example, if @file{texinfo.cnf} contains the line +@samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents +will be processed with that page size in effect. If you have nothing +to put in @file{texinfo.cnf}, you do not need to create it. + +@cindex Environment variable @code{TEXINPUTS} +@vindex TEXINPUTS +If neither of the above locations for these system files suffice, you +can specify the directories explicitly. For @file{texinfo.tex}, you +can do this by writing the complete path for the file after the +@code{\input} command. Another way, that works for both +@file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{} +might read), is to set the @code{TEXINPUTS} environment variable in +your @file{.profile} or @file{.cshrc} file. + +Whether you use @file{.profile} or @file{.cshrc} depends on +whether you use a Bourne shell-compatible (@code{sh}, @code{bash}, +@code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh}) +command interpreter, respeictvely. + +In a @file{.profile} file, you could use the following @code{sh} command +sequence: + +@example +@group +TEXINPUTS=.:/home/me/mylib: +export TEXINPUTS +@end group +@end example + +@need 1000 +While in a @file{.cshrc} file, you could use the following @code{csh} +command sequence: + +@example +setenv TEXINPUTS .:/home/me/mylib: +@end example + +On MS-DOS/MS-Windows, you'd do this (note the use of the @samp{;} +character as directory separator, instead of @samp{:}): + +@example +@group +set TEXINPUTS=.;d:/home/me/mylib;c: +@end group +@end example + +@noindent +It is customary for DOS/Windows users to put such commands in the +@file{autoexec.bat} file, or in the Windows registry. + +@noindent +These settings would cause @TeX{} to look for @file{\input} file first +in the current directory, indicated by the @samp{.}, then in a +hypothetical user @samp{me}'s @file{mylib} directory, and finally in +the system directories. (A leading, trailing, or doubled @samp{:} +indicates searching the system directories at that point.) + + +@node Overfull hboxes +@section Overfull ``hboxes'' +@cindex Overfull @samp{hboxes} +@cindex @samp{hbox}, overfull +@cindex Final output + +@TeX{} is sometimes unable to typeset a line within the normal +margins. This most often occurs when @TeX{} comes upon what it +interprets as a long word that it cannot hyphenate, such as an +electronic mail network address or a very long identifier. When this +happens, @TeX{} prints an error message like this: + +@example +Overfull @@hbox (20.76302pt too wide) +@end example + +@findex hbox +@noindent +(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. +@samp{@@hbox} is a @TeX{} primitive not used in the Texinfo language.) + +@TeX{} also provides the line number in the Texinfo source file and +the text of the offending line, which is marked at all the places that +@TeX{} considered hyphenation. @xref{Debugging with @TeX{}}, for more +information about typesetting errors. + +If the Texinfo file has an overfull hbox, you can rewrite the sentence +so the overfull hbox does not occur, or you can decide to leave it. A +small excursion into the right margin often does not matter and may not +even be noticeable. + +If you have many overfull boxes and/or an antipathy to rewriting, you +can coerce @TeX{} into greatly increasing the allowable interword +spacing, thus (if you're lucky) avoiding many of the bad line breaks, +like this: + +@findex \emergencystretch +@example +@@tex +\global\emergencystretch = .9\hsize +@@end tex +@end example + +@noindent +(You should adjust the fraction as needed.) This huge value for +@code{\emergencystretch} cannot be the default, since then the typeset +output would generally be of noticeably lower quality; its default +value is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension +containing the current line width. + +@cindex Black rectangle in hardcopy +@cindex Rectangle, black in hardcopy +@cindex Box, ugly black in hardcopy +@cindex Ugly black rectangles in hardcopy +For any overfull boxes you do have, @TeX{} will print a large, ugly, +black rectangle beside the line that contains the overfull hbox unless +told otherwise. This is so you will notice the location of the +problem if you are correcting a draft. + +@findex finalout +To prevent such a monstrosity from marring your final printout, write +the following in the beginning of the Texinfo file on a line of its own, +before the @code{@@titlepage} command: + +@example +@@finalout +@end example + + +@node @code{@@smallbook} +@section @code{@@smallbook}: Printing ``Small'' Books + +@anchor{smallbook}@c old name +@findex smallbook +@cindex Small book size +@cindex Book, printing small +@cindex Page sizes for books +@cindex Size of printed book + +By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch +format. However, you can direct @TeX{} to typeset a document in a 7 by +9.25 inch format that is suitable for bound books by inserting the +following command on a line by itself at the beginning of the Texinfo +file, before the title page: + +@example +@@smallbook +@end example + +@noindent +(Since many books are about 7 by 9.25 inches, this command might better +have been called the @code{@@regularbooksize} command, but it came to be +called the @code{@@smallbook} command by comparison to the 8.5 by 11 +inch format.) + +If you write the @code{@@smallbook} command between the +start-of-header and end-of-header lines, the Texinfo mode @TeX{} +region formatting command, @code{texinfo-tex-region}, will format the +region in ``small'' book size (@pxref{Start of Header}). + +@xref{@code{@@small@dots{}}}, for information about commands that make +it easier to produce examples for a smaller manual. + +@xref{Format with @command{texi2dvi}}, and @ref{Preparing for @TeX{}}, +for other ways to format with @code{@@smallbook} that do not require +changing the source file. + + +@node A4 Paper +@section Printing on A4 Paper +@cindex A4 paper, printing on +@cindex A5 paper, printing on +@cindex Paper size, A4 +@cindex European A4 paper +@findex afourpaper +@findex afivepaper + +You can tell @TeX{} to format a document for printing on European size +A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper}) +command. Write the command on a line by itself near the beginning of +the Texinfo file, before the title page. For example, this is how you +would write the header for this manual: + +@example +@group +\input texinfo @@c -*-texinfo-*- +@@c %**start of header +@@settitle Texinfo +@@afourpaper +@@c %**end of header +@end group +@end example + +@xref{Format with @command{texi2dvi}}, and @ref{Preparing for @TeX{}}, +for other ways to format for different paper sizes that do not require +changing the source file. + +@findex afourlatex +@findex afourwide +You may or may not prefer the formatting that results from the command +@code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in +wide format. + + +@node @code{@@pagesizes} +@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes +@anchor{pagesizes}@c old node name + +@findex pagesizes +@cindex Custom page sizes +@cindex Page sizes, customized +@cindex Text width and height +@cindex Width of text area +@cindex Height of text area +@cindex Depth of text area + +You can explicitly specify the height and (optionally) width of the main +text area on the page with the @code{@@pagesizes} command. Write this +on a line by itself near the beginning of the Texinfo file, before the +title page. The height comes first, then the width if desired, +separated by a comma. Examples: + +@example +@@pagesizes 200mm,150mm @c for b5 paper +@end example +@noindent and +@example +@@pagesizes 11.5in @c for legal paper +@end example + +@cindex B5 paper, printing on +@cindex Legal paper, printing on +This would be reasonable for printing on B5-size paper. To emphasize, +this command specifies the size of the @emph{text area}, not the size of +the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by +8.5@dmn{in} for legal). + +@cindex Margins on page, not controllable +To make more elaborate changes, such as changing any of the page +margins, you must define a new command in @file{texinfo.tex} or +@file{texinfo.cnf}. + +@xref{Format with @command{texi2dvi}}, and @ref{Preparing for @TeX{}}, +for other ways to specify @code{@@pagesizes} that do not require +changing the source file. + + +@node Magnification +@section Magnification +@anchor{Cropmarks and Magnification} @c old name + +@findex \mag @r{(raw @TeX{} magnification)} +@cindex Magnified printing +@cindex Larger or smaller pages +You can attempt to direct @TeX{} to typeset pages larger or smaller +than usual with the @code{\mag} @TeX{} command. Everything that is +typeset is scaled proportionally larger or smaller. (@code{\mag} +stands for ``magnification''.) This is @emph{not} a Texinfo +@@-command, but is a raw @TeX{} command that is prefixed with a +backslash. You have to write this command between @code{@@tex} and +@code{@@end tex} (@pxref{Raw Formatter Commands}). + +Follow the @code{\mag} command with an @samp{=} and then a number that +is 1000 times the magnification you desire. For example, to print pages +at 1.2 normal size, write the following near the beginning of the +Texinfo file, before the title page: + +@example +@group +@@tex +\global\mag=1200 +@@end tex +@end group +@end example + +With some printing technologies, you can print normal-sized copies that +look better than usual by giving a larger-than-normal master to your +print shop. They do the reduction, thus effectively increasing the +resolution. + +Depending on your system, DVI files prepared with a +nonstandard-@code{\mag} may not print or may print only with certain +magnifications. Be prepared to experiment. + + +@node PDF Output +@section PDF Output +@cindex PDF output +@cindex Output, in PDF + +@pindex pdftex +The simplest way to generate PDF output from Texinfo source is to run +the convenience script @command{texi2pdf} (or @command{pdftexi2dvi}); +this executes the @command{texi2dvi} script with the @option{--pdf} +option (@pxref{Format with @command{texi2dvi}}). If for some reason you +want to process the document by hand, you can run the @command{pdftex} +program instead of plain @command{tex}. That is, run @samp{pdftex +foo.texi} instead of @samp{tex foo.texi}. + +@dfn{PDF} stands for `Portable Document Format'. It was invented by +Adobe Systems some years ago for document interchange, based on their +PostScript language. Related links: + +@itemize +@item +GNU GV, a @uref{http://www.gnu.org/software/gv/, Ghostscript-based PDF +reader}. (It can also preview PostScript documents.) + +@item +@code{xpdf}, a freely available standalone +@uref{http://www.foolabs.com/xpdf/, PDF reader} for the X window +system. + +@item +@uref{https://en.wikipedia.org/wiki/Portable_Document_Format, PDF at +Wikipedia}. + +@end itemize + +At present, Texinfo does not provide @samp{@@ifpdf} or @samp{@@pdf} +commands as for the other output formats, since PDF documents contain +many internal low-level offsets and cross-references that would be +hard or impossible to specify at the Texinfo source level. + +PDF files require dedicated software to be displayed, unlike the plain +ASCII formats (Info, HTML) that Texinfo supports. They also tend to +be much larger than the DVI files output by @TeX{} by default. +Nevertheless, a PDF file does define an actual typeset document in a +self-contained file, notably including all the fonts that are used, so +it has its place. + + +@node Obtaining @TeX{} +@section Obtaining @TeX{} +@cindex Obtaining @TeX{} +@cindex @TeX{}, how to obtain + +@TeX{} is a document formatter that is used by the FSF for its +documentation. It is the easiest way to get printed output (e.g., PDF +and PostScript) for Texinfo manuals. TeX is freely redistributable, +and you can get it over the Internet or on physical media. See +@url{http://tug.org/texlive}. + +@c please keep that text in sync with www.gnu.org/prep/FTP + + +@node Generic Translator @command{texi2any} +@chapter @command{texi2any}: The Generic Translator for Texinfo + +@command{texi2any} is the generic translator for Texinfo that can +produce different output formats and is highly customizable. It +supports these formats: + +@table @asis +@item Info (by default, or with @option{--info}), + +@item HTML (with @option{--html}), + +@item plain text (with @option{--plaintext}), + +@item Docbook (with @option{--docbook}), + +@item Texinfo XML (with @option{--xml}). +@end table + +@command{makeinfo} is an alias for @command{texi2any}. By default, +both @command{texi2any} and @command{makeinfo} generate Info output; +indeed, there are no differences in behavior based on the name. + +Beside these default formats, command line options to +@command{texi2any} can change many aspects of the output. Beyond +that, initialization files provide even more control over the final +output---nearly anything not specified in the Texinfo input file. +Initialization files are written in Perl, like the main program, and +anything which can be specified on the command line can also be +specified within a initialization file. + +The rest of this chapter goes into the details. + +@menu +* Reference Implementation:: @command{texi2any}: the reference implementation. +* Invoking @command{texi2any}:: Running the translator from a shell. +* @command{texi2any} Environment Variables:: +* @command{texi2any} Printed Output:: Calling @command{texi2dvi}. +* Pointer Validation:: How to check that pointers point somewhere. +* Customization Variables:: Configuring @command{texi2any}. +* Internationalization of Document Strings:: Translating program-inserted text. +* Invoking @command{pod2texi}:: Translating Perl pod to Texinfo. +* @command{texi2html}:: An ancestor of @command{texi2any}. +@end menu + + +@node Reference Implementation +@section @command{texi2any}: A Texinfo Reference Implementation + +@cindex @command{texi2any}, as reference implementation +@cindex Reference implementation +@cindex Implementation, @command{texi2any} as reference + +Above, we called @command{texi2any} ``the'' translator for Texinfo +instead of just ``a'' translator, even though (of course) it's +technically and legally possible for other implementations to be +written. The reason is that alternative implementations are very +likely to have subtle, or not-so-subtle, differences in behavior, and +thus Texinfo documents would become dependent on the processor. +Therefore, it is important to have a reference implementation that +defines parts of the language not fully specified by the manual (often +intentionally so). It is equally important to have consistent +command-line options and other behavior for all processors. + +@cindex Tree representation of documents +@cindex Syntax tree representation of documents +@cindex Abstract syntax tree representation of documents +For this reason, the once-independent @command{texi2html} Perl Texinfo +processor was made compatible with the C implementation of +@command{makeinfo}, to avoid continuing with two different +implementations (@pxref{History}). The current implementation, +@command{texi2any}, serves as the reference implementation. It +inherited the design of customization and other features from +@command{texi2html} (for more on @command{texi2html} compatibility, +@pxref{@command{texi2html}}). However, @code{texi2any} is a full +reimplementation: it constructs a tree-based representation of the +input document for all back-ends to work from. + +@cindex Texinfo language tests +@cindex Tests, of Texinfo language +Extensive tests of the language were developed at the same time as +@command{texi2any}; we plead with anyone thinking of writing a program +to parse Texinfo input to at least make use of these tests. + +@cindex Examples of using @command{texi2any} +@findex Texinfo::Parser module +The @command{texi2html} wrapper script (@pxref{@command{texi2html}}) +provides a very simple example of calling @command{texi2any} from a +shell script; it's in @file{util/texi2html} in the Texinfo sources. +More consequentially, @command{texi-elements-by-size} is an example +Perl script using the @code{Texinfo::Parser} module interface; it's +also in the @file{util} source directory. (Its functionality may also +be useful to authors; @pxref{texi-elements-by-size}.) + +@cindex Future of Texinfo implementations +With the release of @command{texi2any} as the reference +implementation, development of both the C implementation of +@command{makeinfo} and @command{texi2html} has been halted. Going +forward, we ask authors of Texinfo documents to use only +@command{texi2any}. + + +@node Invoking @command{texi2any} +@section Invoking @command{texi2any}/@command{makeinfo} from a Shell + +@anchor{Invoking makeinfo} +@pindex makeinfo +@pindex texi2any + +To process a Texinfo file, invoke @command{texi2any} or +@command{makeinfo} (the two names are synonyms for the same program; +we'll use the names interchangeably) followed by the name of the +Texinfo file. Also select the format you want to output with the +appropriate command line option (default is Info). Thus, to create +the Info file for Bison, type the following to the shell: + +@example +texi2any --info bison.texinfo +@end example + +You can specify more than one input file name; each is processed in +turn. If an input file name is @samp{-}, standard input is read. + +@anchor{@command{makeinfo} Options} +@c anchor{makeinfo options}@c prev name, but case-insensitive clash +@cindex @code{makeinfo} options +@cindex Options for @code{makeinfo} +@anchor{texi2any Options} +@cindex @code{texi2any} options +@cindex Options for @code{texi2any} + +The @command{texi2any} program accepts many options. Perhaps the +most basic are those that change the output format. By default, +@command{texi2any} outputs Info. + +Each command line option is either a long name preceded by @samp{--} +or a single letter preceded by @samp{-}. You can use abbreviations +for the long option names as long as they are unique. + +For example, you could use the following shell command to create an +Info file for @file{bison.texinfo} in which lines are filled to only +68 columns: + +@example +texi2any --fill-column=68 bison.texinfo +@end example + +You can write two or more options in sequence, like this: + +@example +texi2any --no-split --fill-column=70 @dots{} +@end example + +@noindent +(This would keep the Info file together as one possibly very long +file and would also set the fill column to 70.) + +The options are (approximately in alphabetical order): + +@table @code +@item --commands-in-node-names +@opindex --commands-in-node-names +This option now does nothing, but remains for compatibility. (It used +to ensure that @@-commands in node names were expanded throughout the +document, especially @code{@@value}. This is now done by default.) + +@item --conf-dir=@var{path} +@opindex --conf-dir=@var{path} +Prepend @var{path} to the directory search list for finding +customization files that may be loaded with @option{--init-file} (see +below). The @var{path} value can be a single directory, or a list of +several directories separated by the usual path separator character +(@samp{:} on Unix-like systems, @samp{;} on Windows). @c @xref{Loading +@c Init Files}. + +@item --css-include=@var{file} +@opindex --css-include +When producing HTML, literally include the contents of @var{file}, +which should contain W3C cascading style sheets specifications, in the +@samp{<style>} block of the HTML output. If @var{file} is @samp{-}, +read standard input. @xref{HTML CSS}. + +@item --css-ref=@var{url} +@opindex --css-ref +When producing HTML, add a @samp{<link>} tag to the output which +references a cascading style sheet at @var{url}. This allows using +standalone style sheets. + +@item -D @var{var} +@itemx -D '@var{var} @var{value}' +@opindex -D @var{var} +Cause the Texinfo variable @var{var} to be defined. This is +equivalent to @code{@@set @var{var}} in the Texinfo file +(@pxref{@code{@@set @@clear @@value}}). + +The argument to the option is always one word to the shell; if it +contains internal whitespace, the first word is taken as the variable +name and the remainder as the value. For example, @code{-D 'myvar +someval'} is equivalent to @code{@@set myvar someval}. + +@item --disable-encoding +@itemx --enable-encoding +@opindex --disable-encoding +@opindex --enable-encoding +By default, or with @option{--enable-encoding}, output accented and +special characters in Info and plain text output based on +@samp{@@documentencoding}. With @option{--disable-encoding}, 7-bit +ASCII transliterations are output. @xref{@code{@@documentencoding}}, +and @ref{Inserting Accents}. + +@item --docbook +@opindex --docbook +Generate Docbook output (rather than Info). + +@item --document-language=@var{lang} +@opindex --document-language +Use @var{lang} to translate Texinfo keywords which end up in the +output document. The default is the locale specified by the +@code{@@documentlanguage} command if there is one, otherwise English +(@pxref{@code{@@documentlanguage}}). + +@item --dvi +@opindex --dvi +Generate a TeX DVI file using @command{texi2dvi}, rather than Info +(@pxref{@command{texi2any} Printed Output}). + +@item --dvipdf +@opindex --dvipdf +Generate a PDF file using @command{texi2dvi --dvipdf}, rather than +Info (@pxref{@command{texi2any} Printed Output}). + +@item --error-limit=@var{limit} +@itemx -e @var{limit} +@opindex --error-limit=@var{limit} +@opindex -e @var{limit} +Report @var{LIMIT} errors before aborting (on the assumption that +continuing would be useless); default 100. + +@item --fill-column=@var{width} +@itemx -f @var{width} +@opindex --fill-column=@var{width} +@opindex -f @var{width} +Specify the maximum number of columns in a line; this is the +right-hand edge of a line. Paragraphs that are filled will be filled +to this width. (Filling is the process of breaking up and connecting +lines so that lines are the same length as or shorter than the number +specified as the fill column. Lines are broken between words.) The +default value is 72. + +@item --footnote-style=@var{style} +@itemx -s @var{style} +@opindex --footnote-style=@var{style} +@opindex -s @var{style} +Set the footnote style to @var{style}: either @samp{end} for the end +node style (the default) or @samp{separate} for the separate node +style. The value set by this option overrides the value set in a +Texinfo file by a @code{@@footnotestyle} command (@pxref{Footnote +Styles}). + +When the footnote style is @samp{separate}, @code{makeinfo} makes a +new node containing the footnotes found in the current node. When the +footnote style is @samp{end}, @code{makeinfo} places the footnote +references at the end of the current node. + +In HTML, when the footnote style is @samp{end}, or if the output is +not split, footnotes are put at the end of the output. If set to +@samp{separate}, and the output is split, they are placed in a +separate file. + +@item --force +@itemx -F +@opindex --force +@opindex -F +Ordinarily, if the input file has errors, the output files are not +created. With this option, they are preserved. + +@item --help +@itemx -h +@opindex --help@r{, for @command{texi2any}} +@opindex -h +Print a message with available options and basic usage, then exit +successfully. + +@item --html +@opindex --html +Generate HTML output (rather than Info). By default, the HTML output +is split into one output file per Texinfo source node, and the split +output is written into a subdirectory based on the name of the +top-level Info file. @xref{Generating HTML}. + +@item -I @var{path} +@opindex -I @var{path} +Append @var{path} to the directory search list for finding files that +are included using the @code{@@include} command. By default, +@code{texi2any} searches only the current directory. If @var{path} is +not given, the current directory is appended. The @var{path} value +can be a single directory or a list of several directories separated +by the usual path separator character (@samp{:} on Unix-like systems, +@samp{;} on Windows). + +@item --ifdocbook +@opindex --ifdocbook +@itemx --ifhtml +@opindex --ifhtml +@itemx --ifinfo +@opindex --ifinfo +@itemx --ifplaintext +@opindex --ifplaintext +@itemx --iftex +@opindex --iftex +@itemx --ifxml +@opindex --ifxml +For the given format, process @samp{@@if@var{format}} and +@samp{@@@var{format}} commands, and do not process +@samp{@@ifnot@var{format}}, regardless of the format being output. +For instance, if @option{--iftex} is given, then @samp{@@iftex} and +@samp{@@tex} blocks will be read, and @samp{@@ifnottex} blocks will be +ignored. + +@item --info +@opindex --info +Generate Info output. By default, if the output file contains more +than about 300,000 bytes, it is split into shorter subfiles of about +that size. The name of the output file and any subfiles is determined +by @code{@@setfilename} (@pxref{@code{@@setfilename}}). @xref{Tag and +Split Files}. + +@item --init-file=@var{file} +@opindex --init-file=@var{file} +Load @var{file} as code to modify the behavior and output of the +generated manual. It is customary to use the @code{.pm} or the +@code{.init} extensions for these customization files, but that is not +enforced; the @var{file} name can be anything. The +@option{--conf-dir} option (see above) can be used to add to the list +of directories in which these customization files are searched for. +@c @xref{Loading Init Files}. + +@item --internal-links=@var{file} +@opindex --internal-links=@var{file} +@cindex Internal links, of HTML +In HTML mode, output a tab-separated file containing three columns: +the internal link to an indexed item or item in the table of contents, +the name of the index (or table of contents) in which it occurs, and +the term which was indexed or entered. The items are in the natural +sorting order for the given element. This dump can be useful for +post-processors. + +@item --macro-expand=@var{file} +@itemx -E @var{file} +@opindex --macro-expand=@var{file} +@opindex -E @var{file} +Output the Texinfo source, with all Texinfo macros expanded, to +@var{file}. Normally, the result of macro expansion is used +internally by @code{makeinfo} and then discarded. + +@item --no-headers +@opindex --no-headers +@cindex Node separators, omitting with @option{--no-headers} +@cindex Generating plain text files with @option{--no-headers} +@cindex Menus, omitting with @option{--no-headers} +Do not include menus or node separator lines in the output. + +When generating Info, this is the same as using @option{--plaintext}, +resulting in a simple plain text file. Furthermore, +@code{@@setfilename} is ignored, and output is to standard output +unless overridden with @option{-o}. (This behavior is for backward +compatibility.) + +@cindex Navigation links, omitting +When generating HTML, and output is split, also output navigation +links only at the beginning of each file. If output is not split, do +not include navigation links at the top of each node at all. +@xref{Generating HTML}. + +@item --no-ifdocbook +@opindex --no-ifdocbook +@itemx --no-ifhtml +@opindex --no-ifhtml +@itemx --no-ifinfo +@opindex --no-ifinfo +@itemx --no-ifplaintext +@opindex --no-ifplaintext +@itemx --no-iftex +@opindex --no-iftex +@itemx --no-ifxml +@opindex --no-ifxml +For the given format, do not process @samp{@@if@var{format}} and +@samp{@@@var{format}} commands, and do process +@samp{@@ifnot@var{format}}, regardless of the format being output. +For instance, if @option{--no-ifhtml} is given, then @samp{@@ifhtml} +and @samp{@@html} blocks will not be read, and @samp{@@ifnothtml} +blocks will be. + +@item --no-node-files +@itemx --node-files +@opindex --no-node-files +@opindex --node-files +When generating HTML, create redirection files for anchors and any +nodes not already output with the file name corresponding to the node +name (@pxref{HTML Xref Node Name Expansion}). This makes it possible +for section- and chapter-level cross-manual references to succeed +(@pxref{HTML Xref Configuration}). + +If the output is split, this is enabled by default. If the output is +not split, @option{--node-files} enables the creation of the +redirection files, in addition to the monolithic main output file. +@option{--no-node-files} suppresses the creation of redirection files +in any case. This option has no effect with any output format other +than HTML@. @xref{Generating HTML}. + +@item --no-number-footnotes +@opindex --no-number-footnotes +Suppress automatic footnote numbering. By default, footnotes are +numbered sequentially within a node, i.e., the current footnote number +is reset to 1 at the start of each node. + +@item --no-number-sections +@itemx --number-sections +@opindex --no-number-sections +@opindex --number-sections +With @option{--number_sections} (the default), output chapter, +section, and appendix numbers as in printed manuals. This works only +with hierarchically-structured manuals. You should specify +@code{--no-number-sections} if your manual is not normally structured. + +@item --no-pointer-validate +@itemx --no-validate +@opindex --no-pointer-validate +@opindex --no-validate +@cindex Pointer validation, suppressing from command line +Suppress the pointer-validation phase of @code{makeinfo}---a dangerous +thing to do. This can also be done with the @code{@@novalidate} +command (@pxref{Use @TeX{}}). Normally, consistency checks are made +to ensure that cross-references can be resolved, etc. @xref{Pointer +Validation}. + +@item --no-warn +@opindex --no-warn +Suppress warning messages (but not error messages). + +@item --output=@var{file} +@itemx -o @var{file} +@opindex --output=@var{file} +@opindex -o @var{file} +Specify that the output should be directed to @var{file}. This +overrides any file name specified in a @code{@@setfilename} command +found in the Texinfo source. If neither @code{@@setfilename} nor this +option are specified, the input file name is used to determine the +output name. @xref{@code{@@setfilename}}. + +If @var{file} is @samp{-}, output goes to standard output and +@samp{--no-split} is implied. + +If @var{file} is a directory or ends with a @samp{/} the usual rules +are used to determine the output file name (namely, use +@code{@@setfilename} or the input file name) but the files are written +to the @var{file} directory. For example, @samp{makeinfo -o bar/ +foo.texi}, with or without @option{--no-split}, will write +@file{bar/foo.info}, and possibly other files, under @file{bar/}. + +When generating HTML and output is split, @var{file} is used as the +name for the directory into which all files are written. For example, +@samp{makeinfo -o bar --html foo.texi} will write +@file{bar/index.html}, among other files. + +@item --output-indent=@var{val} +@opindex --outputindent +This option now does nothing, but remains for compatibility. (It used +to alter indentation in XML/Docbook output.) + +@item -P @var{path} +@opindex -P @var{path} +Prepend @var{path} to the directory search list for @code{@@include}. +If @var{path} is not given, the current directory is prepended. See +@samp{-I} above. + +@item --paragraph-indent=@var{indent} +@itemx -p @var{indent} +@opindex --paragraph-indent=@var{indent} +@opindex -p @var{indent} +Set the paragraph indentation style to @var{indent}. The value set by +this option overrides the value set in a Texinfo file by an +@code{@@paragraphindent} command (@pxref{@code{@@paragraphindent}}). +The value of @var{indent} is interpreted as follows: + +@table @asis +@item @samp{asis} +Preserve any existing indentation (or lack thereof) at the beginnings +of paragraphs. + +@item @samp{0} or @samp{none} +Delete any existing indentation. + +@item @var{num} +Indent each paragraph by @var{num} spaces. +@end table + +The default is to indent by two spaces, except for paragraphs +following a section heading, which are not indented. + +@item --pdf +@opindex --pdf +Generate a PDF file using @command{texi2dvi --pdf}, rather than Info +(@pxref{@command{texi2any} Printed Output}). + +@item --plaintext +@opindex --plaintext +@cindex Plain text output with @option{--plaintext} +@cindex ASCII text output with @option{--plaintext} +@cindex Generating plain text files with @option{--plaintext} +@cindex Node separators, omitting with @option{--plaintext} +@cindex Menus, omitting with @option{--plaintext} +@cindex @file{INSTALL} file, generating +Output a plain text file (rather than Info): do not include menus or +node separator lines in the output. This results in a straightforward +plain text file that you can (for example) send in email without +complications, or include in a distribution (for example, an +@file{INSTALL} file). + +With this option, @code{@@setfilename} is ignored and the output goes +to standard output by default; this can be overridden with @option{-o}. + +@item --ps +@opindex --ps +Generate a PostScript file using @command{texi2dvi --ps}, rather than +Info (@pxref{@command{texi2any} Printed Output}). + +@item --set-customization-variable @var{var}=@var{value} +@itemx -c @var{var}=@var{value} +@opindex --set-customization-variable @var{var}=@var{value} +@opindex -c @var{var}=@var{value} +Set the customization variable @var{var} to @var{value}. The @code{=} +is optional, but both @var{var} and @var{value} must be quoted to the +shell as necessary so the result is a single word. Many aspects of +@command{texi2any} behavior and output may be controlled by +customization variables, beyond what can be set in the document by +@@-commands and with other command line switches. @xref{Customization +Variables}. + +@item --split=@var{how} +@itemx --no-split +@opindex --split=@var{how} +@opindex --no-split +@cindex Splitting of output files +@cindex Output file splitting +@anchor{Splitting Output} +@c +When generating Info, by default large output files are split into +smaller subfiles, of approximately 300k bytes. When generating HTML, +by default each output file contains one node (@pxref{Generating +HTML}). @option{--no-split} suppresses this splitting of the output. + +Alternatively, @option{--split=@var{how}} may be used to specify at +which level the HTML output should be split. The possible values for +@var{how} are: + +@table @samp +@item chapter +The output is split at @code{@@chapter} and other sectioning +@@-commands at this level (@code{@@appendix}, etc.). + +@item section +The output is split at @code{@@section} and similar. + +@item node +The output is split at every node. This is the default. +@end table + +Plain text output can be split similarly to HTML@. This may be useful +for extracting sections from a Texinfo document and making them +available as separate files. + +@item --split-size=@var{num} +@opindex --split-size=@var{num} +Keep Info files to at most @var{num} characters if possible; default +is 300,000. (However, a single node will never be split across Info +files.) + +@item --transliterate-file-names +@opindex --transliterate-file-names +Enable transliteration of 8-bit characters in node names for the +purpose of file name creation. @xref{HTML Xref 8-bit Character Expansion}. + +@item -U @var{var} +Cause @var{var} to be undefined. This is equivalent to @code{@@clear +@var{var}} in the Texinfo file (@pxref{@code{@@set @@clear @@value}}). + +@item --verbose +@opindex --verbose +Cause @code{makeinfo} to display messages saying what it is doing. +Normally, @code{makeinfo} only outputs messages if there are errors or +warnings. + +@item --version +@itemx -V +@opindex --version@r{, for @command{texi2any}} +@opindex -V +Print the version number, then exit successfully. + +@item --Xopt @var{str} +@opindex --Xopt @var{str} +Pass @var{str} (a single shell word) to @command{texi2dvi}; may be +repeated (@pxref{@command{texi2any} Printed Output}). + +@item --xml +@opindex --xml +Generate Texinfo XML output (rather than Info). + +@end table + + +@node @command{texi2any} Environment Variables +@section Environment Variables Recognized by @command{texi2any} + +@vindex TEXINFO_OUTPUT_FORMAT +@cindex Environment variable @code{TEXINFO_OUTPUT_FORMAT} +@command{makeinfo} also reads the environment variable +@env{TEXINFO_OUTPUT_FORMAT} to determine the output format, if not +overridden by a command line option. The value should be one of: + +@example +docbook dvi dvipdf html info pdf plaintext ps xml +@end example + +If not set or otherwise specified, Info output is the default. + +The customization variable of the same name is also read; if set, that +overrides an environment variable setting, but not a command-line +option. @xref{Customization Variables and Options}. + +@vindex TEXINFO_XS +@cindex Perl extension modules (XS) +You can control @command{texi2any}'s use of Perl extension modules +by setting the @env{TEXINFO_XS} environment variable. These modules +are compiled native code that the interpreted Perl code can use. +Ideally, these extension modules should just work, and the only noticable +difference they should make is that @command{texi2any} finishes running +sooner. However, you can use this environment variable for the purposes +of troubleshooting: for example, if you have problems with the output of +@command{texi2any} varying depending on whether the extension modules are +in use. + +The following values of @env{TEXINFO_XS} are recognized by +@command{texi2any}: + +@table @samp +@item default +The default behavior. Try to load extension modules, and silently fall +back to the interpreted Perl implementations if this fails. + +@item warn +Try to load extension modules, and if this fails, give a warning message +before falling back to the interpreted Perl implementations. + +@item debug +Try to load extension modules, printing many messages while doing so. + +@item omit +Do not use extension modules. + +@end table + +@vindex TEXINFO_XS_PARSER +Set @env{TEXINFO_XS_PARSER} to @samp{1} to enable the use of the native +code implementation of the parser module. This is the part of +@command{texi2any} that converts Texinfo input into an internal tree +format used for further processing into output formats. This is not +enabled by default due to the greater complexity of this module compared +with the other modules that have a native code implementation, and the +lack of confidence we have that the native code implementation matches +the Perl code in all significant aspects. Despite the lack of maturity +of this module in terms of development and testing, it may be useful for +decreasing @command{texi2any} run times when working on Texinfo +documentation files. Note that some error and warning messages will not +be translated from English if this module is used. + + +@node @command{texi2any} Printed Output +@section @command{texi2any} Printed Output + +@cindex Printed output, through @command{texi2any} +@cindex Output, printed through @command{texi2any} + +To justify the name Texinfo-to-@emph{any}, @command{texi2any} has +basic support for creating printed output in the various formats: +@TeX{} DVI, PDF, and PostScript. This is done via the simple method +of executing the @command{texi2dvi} program when those output formats +are requested, after checking the validity of the input to give users +the benefit of @command{texi2any}'s error checking. If you don't want +such error checking, perhaps because your manual plays advanced @TeX{} +tricks together with @file{texinfo.tex}, just invoke +@command{texi2dvi} directly. + +The output format options for this are @option{--dvi}, +@option{--dvipdf}, @option{--pdf}, and @option{--ps}. @xref{Format +with @command{texi2dvi}}, for more details on these options and general +@command{texi2dvi} operation. In addition, the @option{--verbose}, +@option{--silent}, and @option{--quiet} options are passed on if +specified; the @option{-I} and @option{-o} options are likewise passed +on with their arguments, and @option{--debug} without its argument. + +The only option remaining that is related to the @command{texi2dvi} +invocation is @option{--Xopt}. Here, just the argument is passed on +and multiple @option{--Xopt} options accumulate. This provides a way +to construct an arbitrary command line for @command{texi2dvi}. For +example, running + +@example +texi2any --Xopt -t --Xopt @@a4paper --pdf foo.texi +@end example + +@noindent is equivalent to running + +@example +texi2dvi -t @@a4paper --pdf foo.texi +@end example + +@noindent except for the validity check. + +Although one might wish that other options to @command{texi2any} would +take effect, they don't. For example, running @samp{texi2any +--no-number-sections --dvi foo.texi} still results in a DVI file with +numbered sections. (Perhaps this could be improved in the future, if +requests are received.) + +The actual name of the command that is invoked is specified by the +@code{TEXI2DVI} customization variable (@pxref{Other Customization +Variables}). As you might guess, the default is @samp{texi2dvi}. + +@command{texi2any} itself does not generate any normal output when it +invokes @command{texi2dvi}, only diagnostic messages. + + +@node Pointer Validation +@section Pointer Validation +@cindex Pointer validation with @code{makeinfo} +@cindex Validation of pointers + +If you do not suppress pointer validation with the +@samp{--no-validate} option or the @code{@@novalidate} command in the +source file (@pxref{Use @TeX{}}), @code{makeinfo} will check the +validity of the Texinfo file. + +Most validation checks are different depending on whether node +pointers are explicitly or implicitly determined. With explicit node +pointers, here is the list of what is checked: + +@enumerate +@item +If a `Next', `Previous', or `Up' node reference is a reference to a +node in the current file and is not an external reference such as to +@file{(dir)}, then the referenced node must exist. + +@item +Every node except the `Top' node must have an `Up' pointer. + +@item +The node referenced by an `Up' pointer must itself reference the +current node through a menu item, unless the node referenced by `Up' +has the form @samp{(@var{file})}. +@end enumerate + +With implicit node pointers, the above error cannot occur, as such. +(Which is a major reason why we recommend using this feature of +@code{makeinfo}, and not specifying any node pointers yourself.) + +Instead, @code{makeinfo} checks that the tree constructed from the +document's menus matches the tree constructed from the sectioning +commands. For example, if a chapter-level menu mentions nodes +@var{n1} and @var{n2}, in that order, nodes @var{n1} and @var{n2} must +be associated with @code{@@section} commands in the chapter. + +Finally, with both explicit and implicit node pointers, +@code{makeinfo} checks that every node except the `Top' node is +referenced in a menu. + + +@node Customization Variables +@section Customization Variables + +@quotation Warning +These customization variable names and meanings may change in any +Texinfo release. We always try to avoid incompatible changes, but we +cannot absolutely promise, since needs change over time. +@end quotation + +Many aspects of the behavior and output of @command{texi2any} may be +modified by modifying so-called @dfn{customization variables}. These +fall into a few general categories: + +@itemize @bullet +@item +Those associated with @@-commands; for example, +@code{@@documentlanguage}. + +@item +Those associated with command-line options; for example, the +customization variable @code{SPLIT} is associated with the +@option{--split} command-line option, and @code{TEXINFO_OUTPUT_FORMAT} +allows specifying the output format. + +@item +Those associated with customizing the HTML output. + +@item +Other ad hoc variables. +@end itemize + +Customization variables may set on the command line using +@code{--set-customization-variable '@var{var} @var{value}'} (quoting +the variable/value pair to the shell) or +@code{--set-customization-variable @var{var}=@var{value}} (using +@code{=}). A special @var{value} is @samp{undef}, which sets the +variable to this special ``undefined'' Perl value. + +The sections below give the details for each of these. + +@menu +* Commands: Customization Variables for @@-Commands. +* Options: Customization Variables and Options. +* HTML: HTML Customization Variables. +* Other: Other Customization Variables. +@end menu + + +@node Customization Variables for @@-Commands +@subsection Customization Variables for @@-Commands + +@cindex Customization variables for @@-commands +@cindex @@-commands, customization variables for + +Each of the following @@-commands has an associated customization +variable with the same name (minus the leading @code{@@}): + +@smallexample +@@allowcodebreaks @@clickstyle +@@codequotebacktick @@codequoteundirected +@@contents @@deftypefnnewline +@@documentdescription @@documentencoding @@documentlanguage +@@exampleindent @@firstparagraphindent +@@footnotestyle @@frenchspacing +@@kbdinputstyle @@novalidate +@@paragraphindent @@setfilename +@@shortcontents @@urefbreakstyle +@@validatemenus @@xrefautomaticsectiontitle +@end smallexample + +@c Relevant to TeX only. +@c @@evenfooting @@evenfootingmarks +@c @@evenheading @@evenheadingmarks +@c @@everyfooting @@everyfootingmarks +@c @@everyheading @@everyheadingmarks +@c @@fonttextsize +@c @@headings +@c @@oddfooting @@oddfootingmarks +@c @@oddheading @@oddheadingmarks +@c @@pagesizes +@c @@setchapternewpage + +Setting such a customization variable to a value @samp{foo} is similar +to executing @code{@@@var{cmd} foo}. It is not exactly the same, +though, since any side effects of parsing the Texinfo source are not +redone. Also, some variables do not take Texinfo code when generating +particular formats, but an argument that is already formatted. This +is the case, for example, for HTML for @code{documentdescription}. + +Note that if @command{texi2any} is invoked to process the file with +@TeX{} (e.g., with the @option{--pdf} option), then these customization +variables may not be passed on to @TeX{}. + + +@node Customization Variables and Options +@subsection Customization Variables and Options + +@cindex Customization variables for options +@cindex Options, customization variables for + +The following table gives the customization variables associated with +some command line options. @xref{Invoking @command{texi2any}}, for the +meaning of the options. + +@multitable @columnfractions 0.5 0.5 +@headitem Option @tab Variable +@item +@vindex ENABLE_ENCODING +@option{--enable-encoding} @tab @code{ENABLE_ENCODING} +@item +@option{--document-language} @tab @code{documentlanguage} +@item +@vindex ERROR_LIMIT +@option{--error-limit} @tab @code{ERROR_LIMIT} +@item +@vindex FILLCOLUMN +@option{--fill-column} @tab @code{FILLCOLUMN} +@vindex footnotestyle +@item +@option{--footnote-style} @tab @code{footnotestyle} +@item +@vindex FORCE +@option{--force} @tab @code{FORCE} +@vindex INTERNAL_LINKS +@item +@option{--internal-links} @tab @code{INTERNAL_LINKS} +@item +@vindex MACRO_EXPAND +@option{--macro-expand} @tab @code{MACRO_EXPAND} +@item +@option{--headers} @tab @code{HEADERS}, @code{SHOW_MENU} +@item +@vindex NO_WARN +@option{--no-warn} @tab @code{NO_WARN} +@item +@vindex novalidate +@option{--no-validate} @tab @code{novalidate} +@item +@vindex NUMBER_FOOTNOTES +@option{--number-footnotes} @tab @code{NUMBER_FOOTNOTES} +@item +@vindex NUMBER_SECTIONS +@option{--number-sections} @tab @code{NUMBER_SECTIONS} +@item +@vindex NODE_FILES +@option{--node-files} @tab @code{NODE_FILES} +@item +@vindex OUT +@vindex OUTFILE +@vindex SUBDIR +@option{--output} @tab @code{OUT}, @code{OUTFILE}, + @code{SUBDIR} +@item +@vindex paragraphindent +@option{--paragraph-indent} @tab @code{paragraphindent} +@item +@vindex SILENT +@option{--silent} @tab @code{SILENT} +@item +@vindex SPLIT +@option{--split} @tab @code{SPLIT} +@item +@vindex SPLIT_SIZE +@option{--split-size} @tab @code{SPLIT_SIZE} +@item +@vindex TRANSLITERATE_FILE_NAMES +@option{--transliterate-file-names} @tab @code{TRANSLITERATE_FILE_NAMES} +@item +@vindex VERBOSE +@option{--verbose} @tab @code{VERBOSE} +@end multitable + +Setting such a customization variable to a value @samp{foo} is +essentially the same as specifying the @code{--@var{opt}=foo} if the +option takes an argument, or @code{--@var{opt}} if not. + +@vindex TEXINFO_OUTPUT_FORMAT +In addition, the customization variable @code{TEXINFO_OUTPUT_FORMAT} +allows specifying what @code{makeinfo} outputs, either one of the usual +output formats that can be specified with options, or various other +forms: + +@ftable @samp +@item docbook +@itemx dvi +@itemx dvipdf +@itemx html +@itemx info +@itemx pdf +@itemx plaintext +@itemx ps +@itemx xml +These correspond to the command-line options (and +@code{TEXINFO_OUTPUT_FORMAT} environment variable values) of the same +name. @xref{Invoking @command{texi2any}}. + +@item debugtree +@cindex tree representation, for debugging +@cindex debugging document, with tree representation +Instead of generating a regular output format, output a text representation +of the tree obtained by parsing the input texinfo document. + +@item parse +Do only Texinfo source parsing; there is no output. + +@item plaintexinfo +Output the Texinfo source with all the macros, @code{@@include} and +@code{@@value@{@}} expanded. This is similar to setting +@option{--macro-expand}, but instead of being output in addition to +the normal conversion, output of Texinfo is the main output. + +@item rawtext +@cindex raw text output +Output raw text, with minimal formatting. For example, footnotes are +ignored and there is no paragraph filling. This is used by the parser +for file names and copyright text in HTML comments, for example. + +@item structure +Do only Texinfo source parsing and determination of the document +structure; there is no output. + +@item texinfosxml +@cindex SXML output +@cindex S-expressions, output format +Output the document in TexinfoSXML representation, a syntax for +writing XML data using Lisp S-expressions. + +@item textcontent +@cindex spell checking +@cindex word counting +@pindex detexinfo +@cindex stripping Texinfo commands +Output the text content only, stripped of commands; this is useful for +spell checking or word counting, for example. The trivial +@code{detexinfo} script setting this is in the @file{util} directory +of the Texinfo source as an example. It's one line: + +@example +exec texi2any -c TEXINPUT_OUTPUT_FORMAT=textcontent "$@@" +@end example +@end ftable + + +@node HTML Customization Variables +@subsection HTML Customization Variables + +This table gives the customization variables which apply to HTML +output only. A few other customization variable apply to both HTML +and other output formats; those are given in the next section. + +@vtable @code +@item AVOID_MENU_REDUNDANCY +For HTML@. If set, and the menu entry and menu description are the +same, then do not print the menu description; default false. + +@item AFTER_BODY_OPEN +For HTML@. If set, the corresponding text will appear at the +beginning of each HTML file; default unset. + +@item AFTER_ABOUT +For HTML, when an About-element is output. If set, the corresponding +text will appear at the end of the About element; default unset. + +@item AFTER_OVERVIEW +@itemx AFTER_TOC_LINES +For HTML@. If set, the corresponding text is output after the short +table of contents for @code{AFTER_OVERVIEW} and after the table of +contents for @code{AFTER_TOC_LINES}; otherwise, a default string is +used. At the time of writing, a @code{</div>} element is closed. + +In general, you should set @code{BEFORE_OVERVIEW} if +@code{AFTER_OVERVIEW} is set, and you should set +@code{BEFORE_TOC_LINES} if @code{AFTER_TOC_LINES} is set. + + +@item BASEFILENAME_LENGTH +For HTML@. The maximum length of the base filenames; default 245. +Changing this would make cross-manual references to such long node +names invalid (@pxref{HTML Xref Link Basics}). + +@item BEFORE_OVERVIEW +@itemx BEFORE_TOC_LINES +For HTML@. If set, the corresponding text is output before the short +table of contents for @code{BEFORE_OVERVIEW} and before the table of +contents for @code{BEFORE_TOC_LINES}, otherwise a default string is +used. At the time of writing, a @code{<div ...>} element is opened. + +In general you should set @code{AFTER_OVERVIEW} if +@code{BEFORE_OVERVIEW} is set, and you should set +@code{AFTER_TOC_LINES} if @code{BEFORE_TOC_LINES} is set. + + +@item BIG_RULE +For HTML@. Rule used after and before the top element and before +special elements, but not for footers and headers; default +@code{<hr>}. + +@item BODYTEXT +@cindex @code{<body>} text, customizing +@opindex lang@r{, HTML attribute} +For HTML, the text appearing in @code{<body>}. By default, sets the +HTML @code{lang} attribute to the document language +(@pxref{@code{@@documentlanguage}}). + +@item CASE_INSENSITIVE_FILENAMES +For HTML@. Construct output file names as if the filesystem were case +insensitive (@pxref{HTML Splitting}); default false. + +@item CHAPTER_HEADER_LEVEL +For HTML@. Header formatting level used for chapter level sectioning +commands; default @samp{2}. + +@item CHECK_HTMLXREF +For HTML@. Check that manuals which are the target of external +cross-references (@pxref{Four and Five Arguments}) are present in +@file{htmlxref.cnf} (@pxref{HTML Xref Configuration}); default false. + +@item COMPLEX_FORMAT_IN_TABLE +For HTML@. If set, use tables for indentation of complex formats; default +false. + +@item CSS_LINES +For HTML@. CSS output, automatically determined by default (@pxref{HTML CSS}). + +@item DATE_IN_HEADER +For HTML@. Put the document generation date in the header; off by default. + +@item DEF_TABLE +For HTML@. If set, a @code{<table>} construction for @code{@@deffn} +and similar @@-commands is used (looking more like the @TeX{} output), +instead of definition lists; default false. + +@item DEFAULT_RULE +For HTML@. Rule used between element, except before and after the +top element, and before special elements, and for footers and headers; +default @code{<hr>}. + +@item DO_ABOUT +For HTML@. If set to 0 never do an About special element; +if set to 1 always do an About special element; +default 0. +@c @xref{Output Elements Defined}. + +@item EXTERNAL_DIR +For HTML@. Base directory for external manuals; default none. It is +better to use the general external cross-reference mechanism +(@pxref{HTML Xref Configuration}) than this variable. + +@item EXTRA_HEAD +For HTML@. Additional text appearing within @code{<head>}; default unset. + +@item FOOTNOTE_END_HEADER_LEVEL +For HTML@. Header formatting level used for the footnotes header with +the `end' footnotestyle; default @samp{4}. @xref{Footnote Styles}. + +@item FOOTNOTE_SEPARATE_HEADER_LEVEL +For HTML@. Header formatting level used for the footnotes header with +the `separate' footnotestyle; default @samp{4}. @xref{Footnote +Styles}. + +@item FRAMES +For HTML@. If set, a file describing the frame layout is generated, +together with a file with the short table of contents; default false. + +@item FRAMESET_DOCTYPE +For HTML@. Same as DOCTYPE, but for the file containing the frame +description. + +@item HEADER_IN_TABLE +For HTML@. Use tables for header formatting rather than a simple +@code{<div>} element; default false. + +@item ICONS +For HTML@. Use icons for the navigation panel; default false. + +@item IMAGE_LINK_PREFIX +For HTML@. If set, the associated value is prepended to the image file +links; default unset. + +@item INLINE_CONTENTS +For HTML@. If set, output the contents where the @code{@@contents} and +similar @@-commands are located; default true. This is ignored if +@code{@@set*contentsaftertitlepage} is set (@pxref{Contents}). + +@item INLINE_CSS_STYLE +For HTML@. Put CSS directly in HTML elements rather than at the +beginning of the output; default false. + +@item KEEP_TOP_EXTERNAL_REF +For HTML@. If set, do not ignore @samp{Top} as the first +argument for an external ref to a manual, as is done by default. +@xref{Referring to a Manual as a Whole}. + +@item L2H +For HTML@. If set, @command{latex2html} is used to convert @code{@@math} +and @code{@@tex} sections; default false. Best used with @option{--iftex}. + +@item L2H_CLEAN +(Relevant only if @code{L2H} is set.) If set, the intermediate files +generated in relation with @command{latex2html} are removed; default +true. + +@item L2H_FILE +(Relevant only if @code{L2H} is set.) If set, the given file is used +as @command{latex2html}'s init file; default unset. + +@item L2H_HTML_VERSION +(Relevant only if @code{L2H} is set.) The HTML version used in the +@command{latex2html} call; default unset. + +@item L2H_L2H +(Relevant only if @code{L2H} is set.) The program invoked as +@command{latex2html}; default is @code{latex2html}. + +@item L2H_SKIP +(Relevant only if @code{L2H} is set.) If set to a true value, the +actual call to @command{latex2html} is skipped; previously generated +content is reused instead. If set to 0, the cache is not used at all. +If set to @samp{undef}, the cache is used for as many @TeX{} fragments as +possible and for any remaining the command is run. The default is +@samp{undef}. + +@item L2H_TMP +(Relevant only if @code{L2H} is set.) Set the directory used for +temporary files. None of the file name components in this directory +name may start with @samp{.}; otherwise, @command{latex2html} will +fail (because of @command{dvips}). The default is the empty string, +which means the current directory. + +@item MAX_HEADER_LEVEL +For HTML@. Maximum header formatting level used (higher header +formatting level numbers correspond to lower sectioning levels); +default @samp{4}. + +@item MENU_SYMBOL +For HTML@. Symbol used in front of menu entries when node names are used +for menu entries formatting; default @samp{•}. + +@item MONOLITHIC +For HTML@. Output only one file including the table of contents. Set +by default, but only relevant when the output is not split. + +@item NO_CSS +For HTML@. Do not use CSS; default false. @xref{HTML CSS}. + +@item NODE_FILE_EXTENSION +For HTML@. Extension for node files if @code{NODE_FILENAMES} is set; +default @samp{html}. + +@item PRE_ABOUT +For HTML, when an About element is output. If set to a text string, +this text will appear at the beginning of the About element. If set +to a reference on a subroutine, the result of the subroutine call will +appear at the beginning of the About element. If not set (the +default), default text is used. + +@item PRE_BODY_CLOSE +For HTML@. If set, the given text will appear at the footer of each +HTML file; default unset. + +@item PROGRAM_NAME_IN_FOOTER +For HTML@. If set, output the program name and miscellaneous related +information in the page footers; default false. + +@item SECTION_NAME_IN_TITLE +For HTML@. If set, when output is split, use the argument of the +chapter structuring command (e.g., @code{@@chapter} or @code{@@section}) +in the @code{<title>} instead of the argument to @code{@@node}. + +@item SHORTEXTN +For HTML@. If set, use @samp{.htm} as extension; default false. + +@item SHOW_TITLE +For HTML@. If set, output the title at the beginning of the document; +default true. + +@item SIMPLE_MENU +For HTML@. If set, use a simple preformatted style for the menu, +instead of breaking down the different parts of the menu; default false. +@xref{Menu Parts}. + +@item TOC_LINKS +For HTML@. If set, links from headings to toc entries are created; +default false. + +@item TOP_FILE +This file name may be used for the top-level file. The extension is +set appropriately, if necessary. This is used to override the default, +and is, in general, only taken into account when output is split, and +for HTML@. + +@item TOP_NODE_FILE +For HTML@. File name used for the Top node, if @code{NODE_FILENAMES} +is set; default is @code{index}. + +@item TOP_NODE_FILE_TARGET +For HTML@. File name used for the Top node in cross-references; +default is @code{index}. + +@item TOP_NODE_UP_URL +For HTML@. A url used for @code{(dir)} references; the default is +@code{undef}, meaning that the normal rules apply, typically leading +to a link to @samp{dir.html} from an implicit or explicit reference to +@samp{(dir)} (@pxref{HTML Xref}). For more about the Top node +pointers, @pxref{First Node}. For overriding the Up pointer in other +formats, see @code{TOP_NODE_UP} in @ref{Other Customization +Variables}. + +@item USE_ACCESSKEY +@cindex @code{accesskey}, customization variable for +For HTML@. Use @code{accesskey} in cross-references; default true. + +@item USE_ISO +For HTML@. Use entities for doubled single-quote characters +(@pxref{Inserting Quotation Marks}), and @samp{---} and @samp{--} +(@pxref{Conventions}); default true. + +@item USE_LINKS +@cindex @code{<link>} HTML tag, in @code{<head>} +@cindex @code{<head>} HTML tag, and @code{<link>} +For HTML@. Generate @code{<link>} elements in the HTML @code{<head>} +output; default true. + +@item USE_REL_REV +For HTML@. Use @code{rel} in cross-references; default true. + +@item VERTICAL_HEAD_NAVIGATION +For HTML@. If set, a vertical navigation panel is used; default false. + +@item WORDS_IN_PAGE +@cindex Navigation panel, bottom of page +@cindex Navigation footer +For HTML, with output split at nodes. Specifies the approximate +minimum page length at which a navigation panel is placed at the +bottom of a page. To avoid ever having the navigation buttons at the +bottom of a page, set this to a sufficiently large number. The +default is 300. + +@item XREF_USE_FLOAT_LABEL +For HTML@. If set, for the float name in cross-references, use the +float label instead of the type followed by the float number +(@pxref{@code{@@float}}). The default is off. + +@item XREF_USE_NODE_NAME_ARG +For HTML@. Only relevant for cross-reference commands with no cross +reference name (second argument). If set to@tie{}1, use the node name +(first) argument in cross-reference @@-commands for the text displayed +as the hyperlink. If set to@tie{}0, use the node name if +@code{USE_NODES} is set, otherwise the section name. If set to +@samp{undef}, use the first argument in preformatted environments, +otherwise use the node name or section name depending on +@code{USE_NODES}. The default is @samp{undef}. + +@end vtable + + +@node Other Customization Variables +@subsection Other Customization Variables + +This table gives the remaining customization variables, which apply to +multiple formats, or affect global behavior, or otherwise don't fit +into the categories of the previous sections. + +@vtable @code +@item CLOSE_QUOTE_SYMBOL +When a closing quote is needed, use this character; default @code{’} +in HTML, @code{’} in Docbook. The default for Info is the same +as @code{OPEN_QUOTE_SYMBOL} (see below). + +@c @item COMPLETE_IMAGE_PATHS +@c If set, the image files are computed to be relative from the document +@c directory to the source manual directory, and then to the image. + +@item CPP_LINE_DIRECTIVES +Recognize @code{#line} directives in a ``preprocessing'' pass +(@pxref{External Macro Processors}); on by default. + +@item DEBUG +If set, debugging output is generated; default is off (zero). +@c The integer value specifies what kinds of debugging output are +@c generated. It is a bitmask. Setting it to 255 ensures having all +@c available debugging output. + +@item DOCTYPE +@vindex SystemLiteral +For Docbook, HTML, XML@. Specifies the @code{SystemLiteral}, the +entity's system identifier. This is a URI which may be used to +retrieve the entity, and identifies the canonical DTD for the +document. The default value is different for each of HTML, Docbook +and Texinfo@tie{}XML. + +@item DUMP_TEXI +For debugging. If set, no conversion is done, only parsing and macro +expansion. If the option @option{--macro-expand} is set, the Texinfo +source is also expanded to the corresponding file. Default false. + +@item DUMP_TREE +For debugging. If set, the tree constructed upon parsing a Texinfo +document is output to standard error; default false. + +@item ENABLE_ENCODING_USE_ENTITY +For HTML, XML@. If @option{--enable-encoding} is set, and there is an +entity corresponding with the letter or the symbol being output, +prefer the entity. Set by default for HTML, but not XML. + +@item EXTERNAL_CROSSREF_SPLIT +For cross-references to other manuals, this determines if the other +manual is considered to be split or monolithic. By default, it is set +based on the value of @code{SPLIT}. @xref{HTML Xref}, and @pxref{HTML +Xref Configuration}. + +@item EXTENSION +The extension added to the output file name. The default is different +for each output format. + +@c @item IDX_SUMMARY +@c If set, for each @code{@@printindex} a file named +@c @file{@var{docname}_@var{idxname}.idx} is created, containing lines of +@c the form: +@c +@c @example +@c @var{key} @var{reference} +@c @end example +@c +@c @noindent sorted alphabetically (case matters). + +@item IGNORE_BEFORE_SETFILENAME +If set, begin outputting at @code{@@setfilename}, if +@code{@@setfilename} is present; default true. + +@item IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME +If set, spaces are ignored after an @@-command that takes braces. +Default true, matching the @TeX{} behavior. + +@item INDEX_ENTRY_COLON +Symbol used between the index entry and the associated node or section; +default @samp{:}. + +@item INDEX_SPECIAL_CHARS_WARNING +If set, warn about @samp{:} in index entry, as it leads to invalid entries in +index menus in output Info files. For Info and plaintext only. + +@anchor{INFO_SPECIAL_CHARS_QUOTE} +@item INFO_SPECIAL_CHARS_QUOTE +If set, whenever there are problematic characters for Info output in +places such as node names or menu items, surround the part of the +construct where they appear with quoting characters, as described in +@ref{Info Format Specification}. @xref{Node Line Requirements}. + +@item INFO_SPECIAL_CHARS_WARNING +If set, warn about problematic constructs for Info output (such as the +string @samp{::}) in node names, menu items, and cross-references; +default true. Do not warn about index entries, since parsing problems +there don't prevent navigation; readers can still relatively easily +find their way to the node in question. + +@item INPUT_ENCODING_NAME +Normalized encoding name suitable for output. Should be a usable +charset name in HTML, typically one of the preferred IANA encoding +names. You should not need to use this variable, since it is set by +@code{@@documentencoding} (@pxref{@code{@@documentencoding}}). + +@item INPUT_PERL_ENCODING +Perl encoding used to process the Texinfo source. You should not need +to use that variable, since it is set by @code{@@documentencoding} +(@pxref{@code{@@documentencoding}}). + +@item MAX_MACRO_CALL_NESTING +The maximal number of recursive calls of @@-commands defined through +@code{@@rmacro}; default 100000. The purpose of this variable is to +avoid infinite recursions. + +@item MENU_ENTRY_COLON +Symbol used between the menu entry and the description; default +empty. + +@item NO_USE_SETFILENAME +If set, do not use @code{@@setfilename} to set the document name; +instead, base the output document name only on the input file name. +The default is false. + +@item NODE_FILENAMES +If set, node names are used to construct file names. By default, it +is set if the output is split by node, or if @code{NODE_FILES} is set +and the output is split in any way. + +@item NODE_NAME_IN_INDEX +If set, use node names in index entries, otherwise prefer section names; +default true. + +@item NODE_NAME_IN_MENU +If set, use node names in menu entries, otherwise prefer section names; +default true. + +@item OPEN_QUOTE_SYMBOL +When an opening quote is needed, e.g., for @samp{@@samp} output, use +the specified character; default @code{‘} for HTML, +@code{‘} for Docbook. For Info, the default depends on the +enabled document encoding (@pxref{@code{@@documentencoding}}); if no +document encoding is set, or the encoding is US-ASCII, etc., @samp{'} +is used. This character usually appears as an undirected single quote +on modern systems. If the document encoding is Unicode, the Info +output uses a Unicode left quote. + +@item OUTPUT_ENCODING_NAME +Normalized encoding name used for output files. Should be a usable +charset name in HTML, typically one of the preferred IANA encoding +names. By default, if an input encoding is set (typically through +@code{@@documentencoding} or @code{INPUT_ENCODING_NAME}), this +information is used to set the output encoding name. If no input +encoding is specified, the default output encoding name may be set by +the output format. In particular, the XML-based formats use +@code{utf-8} for @code{OUTPUT_ENCODING_NAME} if the encoding is not +otherwise specified. @xref{@code{@@documentencoding}}. + +@item OVERVIEW_LINK_TO_TOC +If set, the cross-references in the Overview link to the corresponding +Table of Contents entries; default true. + +@item PACKAGE +@itemx PACKAGE_VERSION +@itemx PACKAGE_AND_VERSION +@itemx PACKAGE_URL +@itemx PACKAGE_NAME +The implementation's short package name, package version, package name +and version concatenated, package url, and full package name, +respectively. By default, these variables are all set through +Autoconf, Automake, and @code{configure}. + +@item PREFIX +The output file prefix, which is prepended to some output file names. +By default it is set by @code{@@setfilename} or from the input file +(@pxref{@code{@@setfilename}}). How this value is used depends on the +value of other customization variables or command line options, such +as whether the output is split and @code{NODE_FILENAMES}. The default +is unset. + +@item PROGRAM +Name of the program used. By default, it is set to the name of the +program launched, with a trailing @samp{.pl} removed. + +@item RENAMED_NODES_FILE +If set, use the value for the renamed nodes description file. If not +set, the file is @file{@var{doc_basename}-noderename.cnf}. +@xref{HTML Xref Link Preservation}. + +@item RENAMED_NODES_REDIRECTIONS +If set, create redirection files for renamed nodes. Set by default +when generating HTML@. + +@item SHOW_MENU +@vindex HEADERS +@opindex --no-headers +If set, Texinfo menus are output. By default, it is set unless +generating Docbook or if @option{--no-headers} is specified. + +@item SORT_ELEMENT_COUNT +@pindex texi-elements-by-size +@cindex Longest nodes, finding +@cindex Sorting nodes by size +If set, the name of a file to which a list of elements (nodes or +sections, depending on the output format) is dumped, sorted by the +number of lines they contain after removal of @@-commands; default +unset. This is used by the program @code{texi-elements-by-size} in +the @file{util/} directory of the Texinfo source distribution +(@pxref{texi-elements-by-size}). + +@item SORT_ELEMENT_COUNT_WORDS +When dumping the elements-by-size file (see preceding item), use word +counts instead of line counts; default false. + +@c @item SPLIT_INDEX +@c For HTML@. If set, the output is split, and the output from +@c @code{@@printindex} happens in a sectioning element at the level of +@c splitting, then split index pages at the next letter after they have +@c more than that many entries. If set to 0, no index splitting. + +@item TEST +If set to true, some variables which are normally dynamically +generated anew for each run (date, program name, version) are set to +fixed and given values. This is useful to compare the output to a +reference file, as is done for the tests. The default is false. + +@item TEXI2DVI +Name of the command used to produce PostScript, PDF, and DVI; default +@samp{texi2dvi}. @xref{@command{texi2any} Printed Output}. + +@item TEXI2HTML +@cindex compatibility, with @command{texi2html} +Generate HTML and try to be as compatible as possible with +@command{texi2html}; default false. + +@item TEXINFO_DTD_VERSION +For XML@. Version of the DTD used in the XML output preamble. The +default is set based on a variable in @file{configure.ac}. + +@item TEXTCONTENT_COMMENT +For stripped text content output (i.e., when +@code{TEXINFO_OUTPUT_FORMAT} is set to @code{textcontent}). If set, +also output comments. Default false. + +@item TOP_NODE_UP +Up node for the Top node; default @samp{(dir)}. For overriding the +url in HTML output, see @code{TOP_NODE_UP_URL} in @ref{HTML +Customization Variables}. + +@item TREE_TRANSFORMATIONS +The associated value is a comma separated list of transformations that +can be applied to the Texinfo tree prior to outputting the result. If +more than one is specified, the ordering is irrelevant; each is always +applied at the necessary point during processing. + +The only one executed by default is +@samp{move_index_entries_after_items} for HTML and Docbook output. +Here's an example of updating the master menu in a document: + +@example +makeinfo \ + -c TREE_TRANSFORMATIONS=regenerate_master_menu \ + -c PLAINTEXINFO=1 \ + mydoc.texi \ + -o /tmp/out +@end example + +@noindent (Caveat: Since @code{PLAINTEXINFO} output does expand +Texinfo macros and conditionals, it's necessary to remove any such +differences before installing the updates in the original document. +This will be remedied in a future release.) + +The following transformations are currently supported (many are used +in the @code{pod2texi} utility distributed with Texinfo; +@pxref{Invoking @command{pod2texi}}): + +@ftable @samp +@item complete_tree_nodes_menus +Add menu entries or whole menus for nodes associated with sections of +any level, based on the sectioning tree. + +@item fill_gaps_in_sectioning +Adds empty @code{@@unnumbered...} sections in a tree to fill gaps in +sectioning. For example, an @code{@@unnumberedsec} will be inserted +if a @code{@@chapter} is followed by a @code{@@subsection}. + +@item insert_nodes_for_sectioning_commands +Insert nodes for sectioning commands lacking a corresponding node. + +@item move_index_entries_after_items +In @code{@@enumerate} and @code{@@itemize}, move index entries +appearing just before an @code{@@item} to just after the +@code{@@item}. Comment lines between index entries are moved too. As +mentioned, this is always done for HTML and Docbook output. + +@item regenerate_master_menu +Update the Top node master menu, either replacing the (first) +@code{@@detailmenu} in the Top node menu, or creating it at the end of +the Top node menu. + +@item simple_menu +Mostly the same as @code{SIMPLE_MENU}: use a simple preformatted style +for the menu. It differs from setting @code{SIMPLE_MENU} in that +@code{SIMPLE_MENU} only has an effect in HTML output. + +@end ftable + +@item USE_NODES +Preferentially use nodes to decide where elements are separated. If +set to false, preferentially use sectioning to decide where elements +are separated. The default is true. + +@item USE_NODE_TARGET +If set, use the node associated with a section for the section target +in cross-references; default true. + +@item USE_NUMERIC_ENTITY +For HTML and XML@. If set, use numeric entities instead of ASCII +characters when there is no named entity. By default, set to true for +HTML. + +@item USE_UP_NODE_FOR_ELEMENT_UP +Fill in up sectioning direction with node direction when there is no +sectioning up direction. In practice this can only happen when there +is no @@top section. Not set by default. + +@item USE_SETFILENAME_EXTENSION +Default is on for Info, off for other output. If set, use exactly +what @code{@@setfilename} gives for the output file name, including +the extension. You should not need to explicitly set this variable. + +@item USE_TITLEPAGE_FOR_TITLE +Use the full @code{@@titlepage} as the title, not a simple title string; +default false. + +@item USE_UNIDECODE +@pindex Text::Unidecode +If set to false, do not use the @code{Text::Unidecode} Perl module to +transliterate more characters; default true. + +@end vtable + + +@node Internationalization of Document Strings +@section Internationalization of Document Strings + +@cindex I18n, of document strings +@cindex Internationalization of document strings +@cindex Document strings, internationalization of +@cindex Output document strings, internationalization of +@cindex Translating strings in output documents + +@vindex documentlanguage @r{customization variable} +@command{texi2any} writes fixed strings into the output document at +various places: cross-references, page footers, the help page, +alternate text for images, and so on. The string chosen depends on +the value of the @code{documentlanguage} at the time of the string +being output (@pxref{@code{@@documentlanguage}}, for the Texinfo +command interface). + +@pindex libintl-perl @r{Gettext implementation} +The Gettext framework is used for those strings (@pxref{Top,,, +gettext, Gettext}). The @code{libintl-perl} package is used as the +@code{gettext} implementation; more specifically, the pure Perl +implementation is used, so Texinfo can support consistent behavior +across all platforms and installations, which would not otherwise be +possible. @code{libintl-perl} is included in the Texinfo distribution +and always installed, to ensure that it is available if needed. It is +also possible to use the system @code{gettext} (the choice can be made +at build-time). + +@vindex texinfo_document @r{Gettext domain} +@cindex Perl format strings for translation +The Gettext domain @samp{texinfo_document} is used for the strings. +Translated strings are written as Texinfo, and may include +@@-commands. In translated strings, the varying parts of the string +are not usually denoted by @code{%s} and the like, but by +@samp{@{arg_name@}}. (This convention is common for @code{gettext} in +Perl and is fully supported in GNU Gettext; @pxref{perl-format,, Perl +Format Strings, gettext, GNU Gettext}.) For example, in the +following, @samp{@{section@}} will be replaced by the section name: + +@example +see @{section@} +@end example + +These Perl-style brace format strings are used for two reasons: first, +changing the order of @code{printf} arguments is only available since +Perl@tie{}5.8.0; second, and more importantly, the order of arguments +is unpredictable, since @@-command expansion may lead to different +orders depending on the output format. + +The expansion of a translation string is done like this: + +@enumerate +@item First, the string is translated. The locale +is @var{@@documentlanguage}@code{.}@var{@@documentencoding}. + +@cindex @code{us-ascii} encoding, and translations +If the @var{@@documentlanguage} has the form @samp{ll_CC}, that is +tried first, and then just @samp{ll}. If that does not exist, and the +encoding is not @code{us-ascii}, then @code{us-ascii} is tried. + +The idea is that if there is a @code{us-ascii} encoding, it means that +all the characters in the charset may be expressed as @@-commands. +For example, there is a @code{fr.us-ascii} locale that can accommodate +any encoding, since all the Latin@tie{}1 characters have associated +@@-commands. On the other hand, Japanese has only a translation +@code{ja.utf-8}, since there are no @@-commands for Japanese +characters. + +@item Next, the string is expanded as Texinfo, and converted. +The arguments are substituted; for example, @samp{@{arg_name@}} is +replaced by the corresponding actual argument. + +@end enumerate + +In the following example, @samp{@{date@}}, @samp{@{program_homepage@}} +and @samp{@{program@}} are the arguments of the string. Since they +are used in @code{@@uref}, their order is not predictable. +@samp{@{date@}}, @samp{@{program_homepage@}} and @samp{@{program@}} are +substituted after the expansion: + +@example +Generated on @@emph@{@{date@}@} using +@@uref@{@{program_homepage@}, @@emph@{@{program@}@}@}. +@end example + +This approach is admittedly a bit complicated. Its usefulness is that +it supports having translations available in different encodings for +encodings which can be covered by @@-commands, and also specifying how +the formatting for some commands is done, independently of the output +format---yet still be language-dependent. For example, the +@samp{@@pxref} translation string can be like this: + +@example +see @{node_file_href@} section `@{section@}\' in @@cite@{@{book@}@} +@end example + +@noindent +which allows for specifying a string independently of the output +format, while nevertheless with rich formatting it may be translated +appropriately in many languages. + + +@node Invoking @command{pod2texi} +@section Invoking @command{pod2texi}: Convert POD to Texinfo + +@pindex pod2texi +@cindex Invoking @code{pod2texi} +@cindex POD, converting to Texinfo +@cindex Perl POD, converting to Texinfo + +The @code{pod2texi} program translates Perl pod documentation file(s) +to Texinfo. There are two basic modes of operation: generating a +standalone manual from each input pod, or (if @code{--base-level=1} or +higher is given) generating Texinfo subfiles suitable for use +with @code{@@include}. + +Although ordinarily this documentation in the Texinfo manual would be +the best place to look, in this case we have documented all the +options and examples in the @code{pod2texi} program itself, since it +may be useful outside of the rest of Texinfo. Thus, please see the +output of @code{pod2texi --help}, the version on the web at +@url{http://www.gnu.org/software/texinfo/manual/pod2texi.html}, etc. + +For an example of using @code{pod2texi} to make Texinfo out of the +Perl documentation itself, see +@url{http://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo, +@file{contrib/perldoc-all}} in the Texinfo source distribution (the +output is available at @url{http://www.gnu.org/software/perl/manual}). + + +@node @command{texi2html} +@section @command{texi2html}: Ancestor of @command{texi2any} + +@pindex texi2html + +@cindex Cons, Lionel +Conceptually, the @command{texi2html} program is the parent of today's +@command{texi2any} program. @command{texi2html} was developed +independently, originally by Lionel Cons in 1998; at the time, +@command{makeinfo} could not generate HTML@. Many other people +contributed to @command{texi2html} over the years. + +The present @command{texi2any} uses little of the actual code of +@command{texi2html}, and has quite a different basic approach to the +implementation (namely, parsing the Texinfo document into a tree), but +still, there is a family resemblance. + +By design, @command{texi2any} supports nearly all the features of +@command{texi2html} in some way. However, we did not attempt to +maintain strict compatibility, so no @command{texi2html} executable is +installed by the Texinfo package. An approximation can be run with an +invocation like this (available as @file{util/texi2html} in the +Texinfo source): + +@example +texi2any --set-customization-variable TEXI2HTML=1 ... +@end example + +@noindent but, to emphasize, this is @emph{not} a drop-in replacement +for the previous @command{texi2html}. Here are the biggest differences: + +@itemize @bullet +@item Most blatantly, the command line options of @command{texi2html} +are now customization variables, for the most part. A table of +approximate equivalents is given below. + +@item The program-level customization API is very different in +@command{texi2any}. + +@item Indices cannot be split. + +@item Translated strings cannot be customized; we hope to introduce +this feature in @command{texi2any} in the future. + +@end itemize + +Aside from the last, we do not intend to reimplement these +differences. Therefore, the route forward for authors is alter +manuals and build processes as necessary to use the new features and +methods of @command{texi2any}. The @command{texi2html} maintainers +(one of whom is the principal author of @command{texi2any}) do not +intend to make further releases. + +@cindex Options of @command{texi2html} +@cindex Command-line options of @command{texi2html} +Here is the table showing @command{texi2html} options and +corresponding @command{texi2any} customization variables. +@c (@pxref{texi2any Output Customization,, @command{texi2any} Output +@c Customization}). + +@multitable {@option{--ignore-preamble-text}} {@code{IGNORE_PREAMBLE_TEXT}} +@item @option{--toc-links} @tab @code{TOC_LINKS} +@item @option{--short-ext} @tab @code{SHORTEXTN} +@item @option{--prefix} @tab @code{PREFIX} +@item @option{--short-ref} @tab @code{SHORT_REF} +@item @option{--idx-sum} @tab @code{IDX_SUMMARY} +@item @option{--def-table} @tab @code{DEF_TABLE} +@item @option{--ignore-preamble-text} @tab @code{IGNORE_PREAMBLE_TEXT} +@item @option{--html-xref-prefix} @tab @code{EXTERNAL_DIR} +@item @option{--l2h} @tab @code{L2H} +@item @option{--l2h-l2h} @tab @code{L2H_L2H} +@item @option{--l2h-skip} @tab @code{L2H_SKIP} +@item @option{--l2h-tmp} @tab @code{L2H_TMP} +@item @option{--l2h-file} @tab @code{L2H_FILE} +@item @option{--l2h-clean} @tab @code{L2H_CLEAN} +@item @option{--use-nodes} @tab @code{USE_NODES} +@item @option{--monolithic} @tab @code{MONOLITHIC} +@item @option{--top-file} @tab @code{TOP_FILE} +@item @option{--toc-file} @tab @code{TOC_FILE} +@item @option{--frames} @tab @code{FRAMES} +@item @option{--menu} @tab @code{SHOW_MENU} +@item @option{--debug} @tab @code{DEBUG} +@item @option{--doctype} @tab @code{DOCTYPE} +@item @option{--frameset-doctype} @tab @code{FRAMESET_DOCTYPE} +@item @option{--test} @tab @code{TEST} +@end multitable + +@cindex @file{texi2oldapi.texi}, for @command{texi2any} +Finally, any @command{texi2html} users seeking more detailed +information can check the draft file @file{doc/texi2oldapi.texi} in +the Texinfo source repository. It consists mainly of very rough +notes, but may still be useful to some. + + +@node Creating and Installing Info Files +@chapter Creating and Installing Info Files + +This chapter describes how to create and install Info files. +@xref{Info Files}, for general information about the file format +itself. + +@menu +* Creating an Info File:: +* Installing an Info File:: +@end menu + + +@node Creating an Info File +@section Creating an Info File +@cindex Creating an Info file +@cindex Info, creating an online file +@cindex Formatting a file for Info + +@code{makeinfo} is a program that converts a Texinfo file into an Info +file, HTML file, or plain text. @code{texinfo-format-region} and +@code{texinfo-format-buffer} are GNU Emacs functions that convert +Texinfo to Info. + +For information on installing the Info file in the Info system, +@pxref{Installing an Info File}. + +@menu +* @command{makeinfo} Advantages:: @command{makeinfo} provides better error checking. +* @code{makeinfo} in Emacs:: How to run @code{makeinfo} from Emacs. +* @code{texinfo-format} commands:: Two Info formatting commands written + in Emacs Lisp are an alternative + to @code{makeinfo}. +* Batch Formatting:: How to format for Info in Emacs batch mode. +* Tag and Split Files:: How tagged and split files help Info + to run better. +@end menu + + +@node @command{makeinfo} Advantages +@subsection @code{makeinfo} Advantages + +@anchor{makeinfo advantages}@c old name + +The @code{makeinfo} utility creates an Info file from a Texinfo source +providing better error messages than either of the Emacs formatting +commands. We recommend it. The @code{makeinfo} program is +independent of Emacs. You can run @code{makeinfo} in any of three +ways: from an operating system shell, from a shell inside Emacs, or by +typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b} command in +Texinfo mode in Emacs. + +The @code{texinfo-format-region} and the @code{texinfo-format-buffer} +commands may be useful if you cannot run @code{makeinfo}. + + +@node @code{makeinfo} in Emacs +@subsection Running @code{makeinfo} Within Emacs + +@c anchor{makeinfo in Emacs}@c prev name +@cindex Running @code{makeinfo} in Emacs +@cindex @code{makeinfo} inside Emacs +@cindex Shell, running @code{makeinfo} in + +You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the +@code{makeinfo-region} or the @code{makeinfo-buffer} commands. In +Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c +C-m C-b} by default. + +@table @kbd +@item C-c C-m C-r +@itemx M-x makeinfo-region +Format the current region for Info. +@findex makeinfo-region + +@item C-c C-m C-b +@itemx M-x makeinfo-buffer +Format the current buffer for Info. +@findex makeinfo-buffer +@end table + +When you invoke @code{makeinfo-region} the output goes to a temporary +buffer. When you invoke @code{makeinfo-buffer} output goes to the +file set with @code{@@setfilename} (@pxref{@code{@@setfilename}}). + +The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands +run the @code{makeinfo} program in a temporary shell buffer. If +@code{makeinfo} finds any errors, Emacs displays the error messages in +the temporary buffer. + +@cindex Errors, parsing +@cindex Parsing errors +@findex next-error +You can parse the error messages by typing @kbd{C-x `} +(@code{next-error}). This causes Emacs to go to and position the +cursor on the line in the Texinfo source that @code{makeinfo} thinks +caused the error. @xref{Compilation, , Running @code{make} or +Compilers Generally, emacs, The GNU Emacs Manual}, for more +information about using the @code{next-error} command. + +In addition, you can kill the shell in which the @code{makeinfo} +command is running or make the shell buffer display its most recent +output. + +@table @kbd +@item C-c C-m C-k +@itemx M-x makeinfo-kill-job +@findex makeinfo-kill-job +Kill the current running @code{makeinfo} job +(from @code{makeinfo-region} or @code{makeinfo-buffer}). + +@item C-c C-m C-l +@itemx M-x makeinfo-recenter-output-buffer +@findex makeinfo-recenter-output-buffer +Redisplay the @code{makeinfo} shell buffer to display its most recent +output. +@end table + +@noindent +(Note that the parallel commands for killing and recentering a @TeX{} +job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode +Printing}.) + +You can specify options for @code{makeinfo} by setting the +@code{makeinfo-options} variable with either the @kbd{M-x +customize} or the @kbd{M-x set-variable} command, or by setting the +variable in your @file{.emacs} initialization file. + +For example, you could write the following in your @file{.emacs} file: + +@example +@group +(setq makeinfo-options + "--paragraph-indent=0 --no-split + --fill-column=70 --verbose") +@end group +@end example + +@noindent +@c Writing these three cross-references using xref results in +@c three references to the same named manual, which looks strange. +@iftex +For more information, see @ref{@command{makeinfo} Options}, as well as +``Easy Customization Interface,'' ``Examining and Setting Variables,'' +and ``Init File'' in @cite{The GNU Emacs Manual}. +@end iftex +@ifnottex +For more information, see@* +@ref{Easy Customization, , Easy Customization Interface, emacs, The GNU Emacs Manual},@* +@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@* +@ref{Init File, , , emacs, The GNU Emacs Manual}, and@* +@ref{@command{makeinfo} Options}. +@end ifnottex + + +@node @code{texinfo-format} commands +@subsection The @code{texinfo-format@dots{}} Commands + +@c anchor{texinfo-format commands}@c prev name + +In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo +file with the @code{texinfo-format-region} command. This formats the +current region and displays the formatted text in a temporary buffer +called @samp{*Info Region*}. + +Similarly, you can format a buffer with the +@code{texinfo-format-buffer} command. This command creates a new +buffer and generates the Info file in it. Typing @kbd{C-x C-s} will +save the Info file under the name specified by the +@code{@@setfilename} line which must be near the beginning of the +Texinfo file. + +@table @kbd +@item C-c C-e C-r +@itemx @code{texinfo-format-region} +@findex texinfo-format-region +Format the current region for Info. + +@item C-c C-e C-b +@itemx @code{texinfo-format-buffer} +@findex texinfo-format-buffer +Format the current buffer for Info. +@end table + +The @code{texinfo-format-region} and @code{texinfo-format-buffer} +commands provide you with some error checking, and other functions can +provide you with further help in finding formatting errors. These +procedures are described in an appendix; see @ref{Catching Mistakes}. +However, the @code{makeinfo} program provides better error checking +(@pxref{@code{makeinfo} in Emacs}). + +A peculiarity of the @code{texinfo-format-buffer} and +@code{texinfo-format-region} commands is that they do not indent (nor +fill) paragraphs that contain @code{@@w} or @code{@@*} commands. + + +@node Batch Formatting +@subsection Batch Formatting +@cindex Batch formatting for Info +@cindex Info batch formatting + +You can format Texinfo files for Info using @code{batch-texinfo-format} +and Emacs batch mode. You can run Emacs in batch mode from any shell, +including a shell inside of Emacs. (@xref{Initial Options,,, +emacs, The GNU Emacs Manual}.) + +Here is a shell command to format all the files that end in +@file{.texinfo} in the current directory: + +@example +emacs -batch -funcall batch-texinfo-format *.texinfo +@end example + +@noindent +Emacs processes all the files listed on the command line, even if an +error occurs while attempting to format some of them. + +Run @code{batch-texinfo-format} only with Emacs in batch mode as shown; +it is not interactive. It kills the batch mode Emacs on completion. + +@code{batch-texinfo-format} is convenient if you lack @code{makeinfo} +and want to format several Texinfo files at once. When you use Batch +mode, you create a new Emacs process. This frees your current Emacs, so +you can continue working in it. (When you run +@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot +use that Emacs for anything else until the command finishes.) + +@node Tag and Split Files +@subsection Tag Files and Split Files +@cindex Making a tag table automatically +@cindex Tag table, making automatically + +If a Texinfo file has more than 30,000 bytes, +@code{texinfo-format-buffer} automatically creates a tag table +for its Info file; @code{makeinfo} always creates a tag table. With +a @dfn{tag table}, Info can jump to new nodes more quickly than it can +otherwise. + +@cindex Indirect subfiles +In addition, if the Texinfo file contains more than about 300,000 +bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the +large Info file into shorter @dfn{indirect} subfiles of about 300,000 +bytes each. Big files are split into smaller files so that Emacs does +not need to make a large buffer to hold the whole of a large Info +file; instead, Emacs allocates just enough memory for the small, split-off +file that is needed at the time. This way, Emacs avoids wasting +memory when you run Info. (Before splitting was implemented, Info +files were always kept short and @dfn{include files} were designed as +a way to create a single, large printed manual out of the smaller Info +files. @xref{Include Files}, for more information. Include files are +still used for very large documents, such as @cite{The Emacs Lisp +Reference Manual}, in which each chapter is a separate file.) + +When a file is split, Info itself makes use of a shortened version of +the original file that contains just the tag table and references to +the files that were split off. The split-off files are called +@dfn{indirect} files. + +The split-off files have names that are created by appending @w{@samp{-1}}, +@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the +@code{@@setfilename} command. The shortened version of the original file +continues to have the name specified by @code{@@setfilename}. + +At one stage in writing this document, for example, the Info file was saved +as the file @file{test-texinfo} and that file looked like this: + +@example +@group +Info file: test-texinfo, -*-Text-*- +produced by texinfo-format-buffer +from file: new-texinfo-manual.texinfo + +^_ +Indirect: +test-texinfo-1: 102 +test-texinfo-2: 50422 +@end group +@group +test-texinfo-3: 101300 +^_^L +Tag table: +(Indirect) +Node: overview^?104 +Node: info file^?1271 +@end group +@group +Node: printed manual^?4853 +Node: conventions^?6855 +@dots{} +@end group +@end example + +@noindent +(But @file{test-texinfo} had far more nodes than are shown here.) Each of +the split-off, indirect files, @file{test-texinfo-1}, +@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file +after the line that says @samp{Indirect:}. The tag table is listed after +the line that says @samp{Tag table:}. + +In the list of indirect files, the number following the file name +records the cumulative number of bytes in the preceding indirect +files, not counting the file list itself, the tag table, or any +permissions text in the first file. In the tag table, the number +following the node name records the location of the beginning of the +node, in bytes from the beginning of the (unsplit) output. + +If you are using @code{texinfo-format-buffer} to create Info files, +you may want to run the @code{Info-validate} command. (The +@code{makeinfo} command does such a good job on its own, you do not +need @code{Info-validate}.) However, you cannot run the @kbd{M-x +Info-validate} node-checking command on indirect files. For +information on how to prevent files from being split and how to +validate the structure of the nodes, see @ref{Using +@code{Info-validate}}. + + +@node Installing an Info File +@section Installing an Info File +@cindex Installing an Info file +@cindex Info file installation +@cindex @file{dir} directory for Info installation + +Info files are usually kept in the @file{info} directory. You can +read Info files using the standalone Info program or the Info reader +built into Emacs. (@xref{Top,,, info, Info}, for an introduction to +Info.) + +@menu +* Directory File:: The top level menu for all Info files. +* New Info File:: Listing a new Info file. +* Other Info Directories:: How to specify Info files that are + located in other directories. +* Installing Dir Entries:: How to specify what menu entry to add + to the Info directory. +* Invoking @command{install-info}:: @code{install-info} options. +@end menu + + +@node Directory File +@subsection The Directory File @file{dir} + +For Info to work, the @file{info} directory must contain a file that +serves as a top level directory for the Info system. By convention, +this file is called @file{dir}. (You can find the location of this file +within Emacs by typing @kbd{C-h i} to enter Info and then typing +@kbd{C-x C-f} to see the pathname to the @file{info} directory.) + +The @file{dir} file is itself an Info file. It contains the top level +menu for all the Info files in the system. The menu looks like +this: + +@example +@group +* Menu: +* Info: (info). Documentation browsing system. +* Emacs: (emacs). The extensible, self-documenting + text editor. +* Texinfo: (texinfo). With one source file, make + either a printed manual using + @@TeX@{@} or an Info file. +@dots{} +@end group +@end example + +Each of these menu entries points to the `Top' node of the Info file +that is named in parentheses. (The menu entry does not need to +specify the `Top' node, since Info goes to the `Top' node if no node +name is mentioned. @xref{Other Info Files, , Nodes in Other Info +Files}.) + +Thus, the @samp{Info} entry points to the `Top' node of the +@file{info} file and the @samp{Emacs} entry points to the `Top' node +of the @file{emacs} file. + +In each of the Info files, the `Up' pointer of the `Top' node refers +back to the @code{dir} file. For example, the line for the `Top' +node of the Emacs manual looks like this in Info: + +@example +File: emacs Node: Top, Up: (DIR), Next: Distrib +@end example + +@noindent +In this case, the @file{dir} file name is written in uppercase +letters---it can be written in either upper- or lowercase. This is not +true in general, it is a special case for @file{dir}. + + +@node New Info File +@subsection Listing a New Info File +@cindex Adding a new Info file +@cindex Listing a new Info file +@cindex New Info file, listing it in @file{dir} file +@cindex Info file, listing a new +@cindex @file{dir} file listing + +To add a new Info file to your system, you must write a menu entry to +add to the menu in the @file{dir} file in the @file{info} directory. +For example, if you were adding documentation for GDB, you would write +the following new entry: + +@example +* GDB: (gdb). The source-level C debugger. +@end example + +@noindent +The first part of the menu entry is the menu entry name, followed by a +colon. The second part is the name of the Info file, in parentheses, +followed by a period. The third part is the description. + +The name of an Info file often has a @file{.info} extension. Thus, the +Info file for GDB might be called either @file{gdb} or @file{gdb.info}. +The Info reader programs automatically try the file name both with and +without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will +try the @file{.inf} extension as well.}; so it is better to avoid +clutter and not to write @samp{.info} explicitly in the menu entry. For +example, the GDB menu entry should use just @samp{gdb} for the file +name, not @samp{gdb.info}. + + +@node Other Info Directories +@subsection Info Files in Other Directories +@cindex Installing Info in another directory +@cindex Info installed in another directory +@cindex Another Info directory +@cindex @file{dir} files and Info directories + +If an Info file is not in the @file{info} directory, there are three +ways to specify its location: + +@enumerate +@item +Write the pathname in the @file{dir} file as the second part of the menu. + +@item +Specify the Info directory name in the @code{INFOPATH} environment +variable in your @file{.profile} or @file{.cshrc} initialization file. +(Only you and others who set this environment variable will be able to +find Info files whose location is specified this way.) + +@item +If you are using Emacs, list the name of the file in a second @file{dir} +file, in its directory; and then add the name of that directory to the +@code{Info-directory-list} variable in your personal or site +initialization file. + +This variable tells Emacs where to look for @file{dir} files (the files +must be named @file{dir}). Emacs merges the files named @file{dir} from +each of the listed directories. (In Emacs version 18, you can set the +@code{Info-directory} variable to the name of only one +directory.) +@end enumerate + +For example, to reach a test file in the @file{/home/bob/info} +directory, you could add an entry like this to the menu in the +standard @file{dir} file: + +@example +* Test: (/home/bob/info/info-test). Bob's own test file. +@end example + +@noindent +In this case, the absolute file name of the @file{info-test} file is +written as the second part of the menu entry. + +@vindex INFOPATH +@cindex Environment variable @code{INFOPATH} +If you don't want to edit the system @file{dir} file, you can tell +Info where to look by setting the @code{INFOPATH} environment variable +in your shell startup file. This works with both the Emacs and +standalone Info readers. + +Specifically, if you use a Bourne-compatible shell such as @code{sh} +or @code{bash} for your shell command interpreter, you set the +@code{INFOPATH} environment variable in the @file{.profile} +initialization file; but if you use @code{csh} or @code{tcsh}, you set +the variable in the @file{.cshrc} initialization file. On +MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in your +@file{autoexec.bat} file or in the registry. Each type of shell uses +a different syntax. + +@itemize @bullet +@item +In a @file{.cshrc} file, you could set the @code{INFOPATH} +variable as follows: + +@smallexample +setenv INFOPATH .:~/info:/usr/local/emacs/info +@end smallexample + +@item +In a @file{.profile} file, you would achieve the same effect by writing: + +@smallexample +INFOPATH=.:$HOME/info:/usr/local/emacs/info +export INFOPATH +@end smallexample + +@item +@pindex autoexec.bat +In a @file{autoexec.bat} file, you write this command (note the +use of @samp{;} as the directory separator, and a different syntax for +using values of other environment variables): + +@smallexample +set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info +@end smallexample +@end itemize + +@noindent +The @samp{.} indicates the current directory as usual. Emacs uses the +@code{INFOPATH} environment variable to initialize the value of Emacs's +own @code{Info-directory-list} variable. The standalone Info reader +merges any files named @file{dir} in any directory listed in the +@env{INFOPATH} variable into a single menu presented to you in the node +called @samp{(dir)Top}. + +@cindex Colon, last in @env{INFOPATH} +However you set @env{INFOPATH}, if its last character is a colon (on +MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced +by the default (compiled-in) path. This gives you a way to augment +the default path with new directories without having to list all the +standard places. For example (using @code{sh} syntax): + +@example +INFOPATH=/home/bob/info: +export INFOPATH +@end example + +@noindent +will search @file{/home/bob/info} first, then the standard directories. +Leading or doubled colons are not treated specially. + +@cindex @file{dir} file, creating your own +When you create your own @file{dir} file for use with +@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by +copying an existing @file{dir} file and replace all the text after the +@samp{* Menu:} with your desired entries. That way, the punctuation +and special @kbd{CTRL-_} characters that Info needs will be present. + +As one final alternative, which works only with Emacs Info, you can +change the @code{Info-directory-list} variable. For example: + +@example +(add-hook 'Info-mode-hook '(lambda () + (add-to-list 'Info-directory-list + (expand-file-name "~/info")))) +@end example + + +@node Installing Dir Entries +@subsection Installing Info Directory Files + +When you install an Info file onto your system, you can use the program +@code{install-info} to update the Info directory file @file{dir}. +Normally the makefile for the package runs @code{install-info}, just +after copying the Info file into its proper installed location. + +@findex dircategory +@findex direntry +In order for the Info file to work with @code{install-info}, you include +the commands @code{@@dircategory} and +@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source +file. Use @code{@@direntry} to specify the menu entries to add to the +Info directory file, and use @code{@@dircategory} to specify which part +of the Info directory to put it in. Here is how these commands are used +in this manual: + +@smallexample +@@dircategory Texinfo documentation system +@@direntry +* Texinfo: (texinfo). The GNU documentation format. +* install-info: (texinfo)Invoking install-info. @dots{} +@dots{} +@@end direntry +@end smallexample + +Here's what this produces in the Info file: + +@smallexample +INFO-DIR-SECTION Texinfo documentation system +START-INFO-DIR-ENTRY +* Texinfo: (texinfo). The GNU documentation format. +* install-info: (texinfo)Invoking install-info. @dots{} +@dots{} +END-INFO-DIR-ENTRY +@end smallexample + +@noindent +The @code{install-info} program sees these lines in the Info file, and +that is how it knows what to do. + +Always use the @code{@@direntry} and @code{@@dircategory} commands near +the beginning of the Texinfo input, before the first @code{@@node} +command. If you use them later on in the input, @code{install-info} +will not notice them. + +@code{install-info} will automatically reformat the description of the +menu entries it is adding. As a matter of convention, the description +of the main entry (above, @samp{The GNU documentation format}) should +start at column 32, starting at zero (as in +@code{what-cursor-position} in Emacs). This will make it align with +most others. Description for individual utilities best start in +column 48, where possible. For more information about formatting see +the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in +@ref{Invoking @command{install-info}}. + +If you use @code{@@dircategory} more than once in the Texinfo source, +each usage specifies the `current' category; any subsequent +@code{@@direntry} commands will add to that category. + +@cindex Free Software Directory +@cindex Dir categories, choosing +@cindex Categories, choosing +When choosing a category name for the @code{@@dircategory} command, we +recommend consulting the @uref{http://www.gnu.org/directory, +Free Software Directory}. If your program is not listed there, +or listed incorrectly or incompletely, please report the situation to +the directory maintainers (@url{http://directory.fsf.org}) so that the +category names can be kept in sync. + +Here are a few examples (see the @file{util/dir-example} file in the +Texinfo distribution for large sample @code{dir} file): + +@display +Emacs +Localization +Printing +Software development +Software libraries +Text creation and manipulation +@end display + +@cindex Invoking nodes, including in dir file +Each `Invoking' node for every program installed should have a +corresponding @code{@@direntry}. This lets users easily find the +documentation for the different programs they can run, as with the +traditional @command{man} system. + + +@node Invoking @command{install-info} +@subsection Invoking @command{install-info} + +@pindex install-info + +@code{install-info} inserts menu entries from an Info file into the +top-level @file{dir} file in the Info system (see the previous sections +for an explanation of how the @file{dir} file works). @code{install-info} +also removes menu entries from the @file{dir} file. It's most often +run as part of software installation, or when constructing a @file{dir} file +for all manuals on a system. Synopsis: + +@example +install-info [@var{option}@dots{}] [@var{info-file} [@var{dir-file}]] +@end example + +If @var{info-file} or @var{dir-file} are not specified, the options +(described below) that define them must be. There are no compile-time +defaults, and standard input is never used. @code{install-info} can +read only one Info file and write only one @file{dir} file per invocation. + +@cindex @file{dir}, created by @code{install-info} +If @var{dir-file} (however specified) does not exist, +@code{install-info} creates it if possible (with no entries). + +@cindex Compressed dir files, reading +@cindex XZ-compressed dir files, reading +@cindex Bzipped dir files, reading +@cindex Lzip-compressed dir files, reading +@cindex LZMA-compressed dir files, reading +@cindex Dir files, compressed +If any input file is compressed with @code{gzip} (@pxref{Top,,, gzip, +Gzip}), @code{install-info} automatically uncompresses it for reading. +And if @var{dir-file} is compressed, @code{install-info} also +automatically leaves it compressed after writing any changes. If +@var{dir-file} itself does not exist, @code{install-info} tries to +open @file{@var{dir-file}.gz}, @file{@var{dir-file}.xz}, +@file{@var{dir-file}.bz2}, @file{@var{dir-file}.lz}, and +@file{@var{dir-file}.lzma}, in that order. + +Options: + +@table @code +@item --add-once +@opindex --add-once@r{, for @command{install-info}} +Specifies that the entry or entries will only be put into a single section. + +@item --align=@var{column} +@opindex --align=@var{column}@r{, for @command{install-info}} +Specifies the column that the second and subsequent lines of menu entry's +description will be formatted to begin at. The default for this option is +@samp{35}. It is used in conjunction with the @samp{--max-width} option. +@var{column} starts counting at 1. + +@item --append-new-sections +@opindex --append-new-sections@r{, for @command{install-info}} +Instead of alphabetizing new sections, place them at the end of the DIR file. + +@item --calign=@var{column} +@opindex --calign=@var{column}@r{, for @command{install-info}} +Specifies the column that the first line of menu entry's description will +be formatted to begin at. The default for this option is @samp{33}. It is +used in conjunction with the @samp{--max-width} option. +When the name of the menu entry exceeds this column, entry's description +will start on the following line. +@var{column} starts counting at 1. + +@item --debug +@opindex --debug@r{, for @command{install-info}} +Report what is being done. + +@item --delete +@opindex --delete@r{, for @command{install-info}} +Delete the entries in @var{info-file} from @var{dir-file}. The file +name in the entry in @var{dir-file} must be @var{info-file} (except for +an optional @samp{.info} in either one). Don't insert any new entries. +Any empty sections that result from the removal are also removed. + +@item --description=@var{text} +@opindex --description=@var{text}@r{, for @command{install-info}} +Specify the explanatory portion of the menu entry. If you don't specify +a description (either via @samp{--entry}, @samp{--item} or this option), +the description is taken from the Info file itself. + +@item --dir-file=@var{name} +@opindex --dir-file=@var{name}@r{, for @command{install-info}} +Specify file name of the Info directory file. This is equivalent to +using the @var{dir-file} argument. + +@item --dry-run +@opindex --dry-run@r{, for @command{install-info}} +Same as @samp{--test}. + +@item --entry=@var{text} +@opindex --entry=@var{text}@r{, for @command{install-info}} +Insert @var{text} as an Info directory entry; @var{text} should have the +form of an Info menu item line plus zero or more extra lines starting +with whitespace. If you specify more than one entry, they are all +added. If you don't specify any entries, they are determined from +information in the Info file itself. + +@item --help +@opindex --help@r{, for @command{texindex}} +Display a usage message with basic usage and all available options, +then exit successfully. + +@item --info-file=@var{file} +@opindex --info-file=@var{file}@r{, for @command{install-info}} +Specify Info file to install in the directory. This is +equivalent to using the @var{info-file} argument. + +@item --info-dir=@var{dir} +@opindex --info-dir=@var{dir}@r{, for @command{install-info}} +Specify the directory where the directory file @file{dir} resides. +Equivalent to @samp{--dir-file=@var{dir}/dir}. + +@item --infodir=@var{dir} +@opindex --infodir=@var{dir}@r{, for @command{install-info}} +Same as @samp{--info-dir}. + +@item --item=@var{text} +@opindex --item=@var{text}@r{, for @command{install-info}} +Same as @samp{--entry=@var{text}}. An Info directory entry is actually +a menu item. + +@item --keep-old +@opindex --keep-old@r{, for @command{install-info}} +Do not replace pre-existing menu entries. When @samp{--remove} is specified, +this option means that empty sections are not removed. + +@item --max-width=@var{column} +@opindex --max-width=@var{column}@r{, for @command{install-info}} +Specifies the column that the menu entry's description will be word-wrapped +at. @var{column} starts counting at 1. + +@item --maxwidth=@var{column} +@opindex --maxwidth=@var{column}@r{, for @command{install-info}} +Same as @samp{--max-width}. + +@item --menuentry=@var{text} +@opindex --menuentry=@var{text}@r{, for @command{install-info}} +Same as @samp{--name}. + +@item --name=@var{text} +@opindex --name=@var{text}@r{, for @command{install-info}} +Specify the name portion of the menu entry. If the @var{text} does +not start with an asterisk @samp{*}, it is presumed to be the text +after the @samp{*} and before the parentheses that specify the Info +file. Otherwise @var{text} is taken verbatim, and is taken as +defining the text up to and including the first period (a space is +appended if necessary). If you don't specify the name (either via +@samp{--entry}, @samp{--item} or this option), it is taken from the +Info file itself. If the Info does not contain the name, the basename +of the Info file is used. + +@item --no-indent +@opindex --no-indent@r{, for @command{install-info}} +Suppress formatting of new entries into the @file{dir} file. + +@item --quiet +@itemx --silent +@opindex --quiet@r{, for @command{install-info}} +@opindex --silent@r{, for @command{install-info}} +Suppress warnings, etc., for silent operation. + +@item --remove +@opindex --remove@r{, for @command{install-info}} +Same as @samp{--delete}. + +@item --remove-exactly +@opindex --remove-exactly@r{, for @command{install-info}} +Also like @samp{--delete}, but only entries if the Info file name +matches exactly; @code{.info} and/or @code{.gz} suffixes are +@emph{not} ignored. + +@item --section=@var{sec} +@opindex --section=@var{sec}@r{, for @command{install-info}} +Put this file's entries in section @var{sec} of the directory. If you +specify more than one section, all the entries are added in each of the +sections. If you don't specify any sections, they are determined from +information in the Info file itself. If the Info file doesn't specify +a section, the menu entries are put into the Miscellaneous section. + +@item --section @var{regex} @var{sec} +@opindex --section @var{regex} @var{sec}@r{, for @command{install-info}} +Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}. + +@code{install-info} tries to detect when this alternate syntax is used, +but does not always guess correctly. Here is the heuristic that +@code{install-info} uses: +@enumerate +@item +If the second argument to @code{--section} starts with a hyphen, the +original syntax is presumed. + +@item +If the second argument to @code{--section} is a file that can be +opened, the original syntax is presumed. + +@item +Otherwise the alternate syntax is used. +@end enumerate + +When the heuristic fails because your section title starts with a +hyphen, or it happens to be a filename that can be opened, the syntax +should be changed to @samp{--regex=@var{regex} --section=@var{sec} +--add-once}. + +@item --regex=@var{regex} +@opindex --regex=@var{regex}@r{, for @command{install-info}} +Put this file's entries into any section that matches @var{regex}. If +more than one section matches, all of the entries are added in each of the +sections. Specify @var{regex} using basic regular expression syntax, more +or less as used with @command{grep}, for example. + +@item --test +@opindex --test@r{, for @command{install-info}} +Suppress updating of the directory file. + +@item --version +@opindex --version@r{, for @command{install-info}} +@cindex Version number, for install-info +Display version information and exit successfully. + +@end table + + +@node Generating HTML +@chapter Generating HTML + +@cindex Generating HTML +@cindex Outputting HTML + +@command{makeinfo} generates Info output by default, but given the +@option{--html} option, it will generate HTML, for web browsers and +other programs. This chapter gives some details on such HTML output. + +@command{makeinfo} has many user-definable customization variables +with which you can influence the HTML output. @xref{Customization +Variables}. + +@command{makeinfo} can also produce output in XML and Docbook formats, +but we do not as yet describe these in detail. @xref{Output Formats}, +for a brief overview of all the output formats. + +@menu +* HTML Translation:: Details of the HTML output. +* HTML Splitting:: How HTML output is split. +* HTML CSS:: Influencing HTML output with Cascading Style Sheets. +* HTML Xref:: Cross-references in HTML output. +@end menu + + +@node HTML Translation +@section HTML Translation + +@cindex HTML translation + +@cindex HTML output, browser compatibility of +First, the HTML generated by @command{makeinfo} is standard +HTML@tie{}4. When first written, it also tried to be compatible with +earlier standards (e.g., HTML@tie{}2.0, RFC-1866). + +Please report output from an +error-free run of @code{makeinfo} which has practical browser +portability problems as a bug (@pxref{Reporting Bugs}). + +@pindex html32.pm +Some known exceptions to HTML@tie{}3.2 (using +@samp{--init-file=html32.pm} produced strict HTML@tie{}3.2 output, but +this has not been tested lately; +@pxref{Invoking @command{texi2any}}): + +@enumerate +@item +HTML@tie{}3.2 tables are generated for the @code{@@multitable} command +(@pxref{Multi-column Tables}), but they should degrade reasonably in +browsers without table support. + +@item +The HTML@tie{}4 @samp{id} attribute is used. + +@item +The HTML@tie{}4 @samp{lang} attribute on the @samp{<html>} attribute +is used. + +@item +Entities that are not in the HTML@tie{}3.2 standard are also used. + +@item +CSS is used (@pxref{HTML CSS}). + +@item +Some HTML@tie{}4 elements are used: @code{span}, @code{thead}, +@code{abbr}, @code{acronym}. + +@end enumerate + +To achieve maximum portability and accessibility among browsers (both +graphical and text-based), systems, and users, the HTML output is +intentionally quite plain and generic. It has always been our goal +for users to be able to customize the output to their wishes via CSS +(@pxref{HTML CSS}) or other means (@pxref{Customization Variables}). +If you cannot accomplish a reasonable customization, feel free to +report that. + +However, we do not wish to depart from our basic goal of widest +readability for the core output. For example, using fancy CSS may +make it possible for the HTML output to more closely resemble the +@TeX{} output in some details, but this result is not even close to +being worth the ensuing difficulties. + +It is also intentionally not our goal, and not even possible, to pass +through every conceivable validation test without any diagnostics. +Different validation tests have different goals, often about pedantic +enforcement of some standard or another. Our overriding goal is to +help users, not blindly comply with standards. + +To repeat what was said at the top: please report output from an +error-free run of @code{makeinfo} which has @emph{practical} browser +portability problems as a bug (@pxref{Reporting Bugs}). + +A few other general points about the HTML output follow. + +@cindex Navigation bar, in HTML output +@strong{Navigation bar:} By default, a navigation bar is inserted at the +start of each node, analogous to Info output. If the +@samp{--no-headers} option is used, the navigation bar is only +inserted at the beginning of split files. Header @code{<link>} +elements in split output can support Info-like navigation with +browsers like Lynx and @w{Emacs W3} which implement this HTML@tie{}1.0 +feature. + +@cindex Footnote styles, in HTML +@strong{Footnotes:} for HTML, when the footnote style is @samp{end}, +or if the output is not split, footnotes are put at the end of the +output. If the footnote style is set to @samp{separate}, and the +output is split, they are placed in a separate file. @xref{Footnote +Styles}. + +@cindex Escaping to HTML +@cindex Raw HTML +@strong{Raw HTML}: @command{makeinfo} will include segments of Texinfo +source between @code{@@ifhtml} and @code{@@end ifhtml} in the HTML +output (but not any of the other conditionals, by default). Source +between @code{@@html} and @code{@@end html} is passed without change +to the output (i.e., suppressing the normal escaping of input +@samp{<}, @samp{>} and @samp{&} characters which have special +significance in HTML)@. @xref{Conditional Commands}. + + +@node HTML Splitting +@section HTML Splitting +@cindex Split HTML output +@cindex HTML output, split + +When splitting output at nodes (which is the default), +@command{makeinfo} writes HTML output into (basically) one output file +per Texinfo source @code{@@node}. + +Each output file name is the node name with spaces replaced by +@samp{-}'s and special characters changed to @samp{_} followed by +their code point in hex (@pxref{HTML Xref}). This is to make it +portable and easy to use as a filename. In the unusual case of two +different nodes having the same name after this treatment, they are +written consecutively to the same file, with HTML anchors so each can +be referred to independently. + +If @command{makeinfo} is run on a system which does not distinguish +case in file names, nodes which are the same except for case (e.g., +@samp{index} and @samp{Index}) will also be folded into the same +output file with anchors. You can also pretend to be on a case +insensitive filesystem by setting the customization variable +@code{CASE_INSENSITIVE_FILENAMES}. + +It is also possible to split at chapters or sections with +@option{--split} (@pxref{Invoking @command{texi2any}}). In that case, +the file names are constructed after the name of the node associated +with the relevant sectioning command. Also, unless +@option{--no-node-files} is specified, a redirection file is output +for every node in order to more reliably support cross-references to +that manual (@pxref{HTML Xref}). + +When splitting, the HTML output files are written into a subdirectory, +with the name chosen as follows: + +@enumerate +@item +@command{makeinfo} first tries the subdirectory with the base name +from @code{@@setfilename} (that is, any extension is removed). For +example, HTML output for @code{@@setfilename gcc.info} would be +written into a subdirectory named @samp{gcc/}. + +@item +If that directory cannot be created for any reason, then +@command{makeinfo} tries appending @samp{.html} to the directory name. +For example, output for @code{@@setfilename texinfo} would be written +to @samp{texinfo.html/}. + +@item +If the @samp{@var{name}.html} directory can't be created either, +@code{makeinfo} gives up. + +@end enumerate + +@noindent In any case, the top-level output file within the directory +is always named @samp{index.html}. + +Monolithic output (@code{--no-split}) is named according to +@code{@@setfilename} (with any @samp{.info} extension is replaced with +@samp{.html}), @code{--output} (the argument is used literally), or +based on the input file name as a last resort +(@pxref{@code{@@setfilename}}). + + +@node HTML CSS +@section HTML CSS +@cindex HTML, and CSS +@cindex CSS, and HTML output +@cindex Cascading Style Sheets, and HTML output + +Cascading Style Sheets (CSS for short) is an Internet standard for +influencing the display of HTML documents: see +@uref{http://www.w3.org/Style/CSS/}. + +By default, @command{makeinfo} includes a few simple CSS commands to +better implement the appearance of some Texinfo environments. Here +are two of them, as an example: + +@example +pre.display @{ font-family:inherit @} +pre.smalldisplay @{ font-family:inherit; font-size:smaller @} +@end example + +A full explanation of CSS is (far) beyond this manual; please see the +reference above. In brief, however, the above tells the web browser +to use a `smaller' font size for @code{@@smalldisplay} text, and to +use the same font as the main document for both @code{@@smalldisplay} +and @code{@@display}. By default, the HTML @samp{<pre>} command uses +a monospaced font. + +You can influence the CSS in the HTML output with two +@command{makeinfo} options: @option{--css-include=@var{file}} and +@option{--css-ref=@var{url}}. + +@pindex texinfo-bright-colors.css +@cindex Visualizing Texinfo CSS +The option @option{--css-ref=@var{url}} adds to each output HTML file +a @samp{<link>} tag referencing a CSS at the given @var{url}. This +allows using external style sheets. You may find the file +@file{texi2html/examples/texinfo-bright-colors.css} useful for +visualizing the CSS elements in Texinfo output. + +The option @option{--css-include=@var{file}} includes the contents +@var{file} in the HTML output, as you might expect. However, the +details are somewhat tricky, as described in the following, to provide +maximum flexibility. + +@cindex @samp{@@import} specifications, in CSS files +The CSS file may begin with so-called @samp{@@import} directives, +which link to external CSS specifications for browsers to use when +interpreting the document. Again, a full description is beyond our +scope here, but we'll describe how they work syntactically, so we can +explain how @command{makeinfo} handles them. + +@cindex Comments, in CSS files +There can be more than one @samp{@@import}, but they have to come +first in the file, with only whitespace and comments interspersed, no +normal definitions. (Technical exception: a @samp{@@charset} +directive may precede the @samp{@@import}'s. This does not alter +@command{makeinfo}'s behavior, it just copies the @samp{@@charset} if +present.) Comments in CSS files are delimited by @samp{/* ... */}, as +in C@. An @samp{@@import} directive must be in one of these two forms: + +@example +@@import url(http://example.org/foo.css); +@@import "http://example.net/bar.css"; +@end example + +As far as @command{makeinfo} is concerned, the crucial characters are +the @samp{@@} at the beginning and the semicolon terminating the +directive. When reading the CSS file, it simply copies any such +@samp{@@}-directive into the output, as follows: + +@itemize +@item If @var{file} contains only normal CSS declarations, it is +included after @command{makeinfo}'s default CSS, thus overriding it. + +@item If @var{file} begins with @samp{@@import} specifications (see +below), then the @samp{import}'s are included first (they have to come +first, according to the standard), and then @command{makeinfo}'s +default CSS is included. If you need to override @command{makeinfo}'s +defaults from an @samp{@@import}, you can do so with the @samp{!@: +important} CSS construct, as in: +@example +pre.smallexample @{ font-size: inherit ! important @} +@end example + +@item If @var{file} contains both @samp{@@import} and inline CSS +specifications, the @samp{@@import}'s are included first, then +@command{makeinfo}'s defaults, and lastly the inline CSS from +@var{file}. + +@item Any @@-directive other than @samp{@@import} and @samp{@@charset} +is treated as a CSS declaration, meaning @command{makeinfo} includes +its default CSS and then the rest of the file. +@end itemize + +If the CSS file is malformed or erroneous, @command{makeinfo}'s output +is unspecified. @command{makeinfo} does not try to interpret the +meaning of the CSS file in any way; it just looks for the special +@samp{@@} and @samp{;} characters and blindly copies the text into the +output. Comments in the CSS file may or may not be included in the +output. + +In addition to the possibilities offered by CSS, @command{makeinfo} +has many user-definable customization variables with which you can +influence the HTML output. @xref{Customization Variables}. + + +@node HTML Xref +@section HTML Cross-references +@cindex HTML cross-references +@cindex Cross-references, in HTML output + +Cross-references between Texinfo manuals in HTML format become, in the +end, a standard HTML @code{<a>} link, but the details are +unfortunately complex. This section describes the algorithm used in +detail, so that Texinfo can cooperate with other programs, such as +@command{texi2html}, by writing mutually compatible HTML files. + +This algorithm may or may not be used for links @emph{within} HTML +output for a Texinfo file. Since no issues of compatibility arise in +such cases, we do not need to specify this. + +We try to support references to such ``external'' manuals in both +monolithic and split forms. A @dfn{monolithic} (mono) manual is +entirely contained in one file, and a @dfn{split} manual has a file +for each node. (@xref{HTML Splitting}.) + +@cindex Dumas, Patrice +The algorithm was primarily devised by Patrice Dumas in 2003--04. + +@menu +* Link Basics: HTML Xref Link Basics. +* Node Expansion: HTML Xref Node Name Expansion. +* Command Expansion: HTML Xref Command Expansion. +* 8-bit Expansion: HTML Xref 8-bit Character Expansion. +* Mismatch: HTML Xref Mismatch. +* Configuration: HTML Xref Configuration. htmlxref.cnf. +* Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf. +@end menu + + +@node HTML Xref Link Basics +@subsection HTML Cross-reference Link Basics +@cindex HTML cross-reference link basics + +For our purposes, an HTML link consists of four components: a host +name, a directory part, a file part, and a target part. We +always assume the @code{http} protocol. For example: + +@example +http://@var{host}/@var{dir}/@var{file}.html#@var{target} +@end example + +The information to construct a link comes from the node name and +manual name in the cross-reference command in the Texinfo source +(@pxref{Cross References}), and from @dfn{external information} +(@pxref{HTML Xref Configuration}). + +We now consider each part in turn. + +The @var{host} is hardwired to be the local host. This could either +be the literal string @samp{localhost}, or, according to the rules for +HTML links, the @samp{http://localhost/} could be omitted entirely. + +The @var{dir} and @var{file} parts are more complicated, and depend on +the relative split/mono nature of both the manual being processed and +the manual that the cross-reference refers to. The underlying idea is +that there is one directory for Texinfo manuals in HTML, and a given +@var{manual} is either available as a monolithic file +@file{@var{manual}.html}, or a split subdirectory +@file{@var{manual}/*.html}. Here are the cases: + +@itemize @bullet +@item +If the present manual is split, and the referent manual is also split, +the directory is @samp{../@var{referent/}} and the file is the +expanded node name (described later). + +@item +If the present manual is split, and the referent manual is mono, the +directory is @samp{../} and the file is @file{@var{referent}.html}. + +@item +If the present manual is mono, and the referent manual is split, the +directory is @file{@var{referent}/} and the file is the expanded node +name. + +@item +If the present manual is mono, and the referent manual is also mono, +the directory is @file{./} (or just the empty string), and the file is +@file{@var{referent}.html}. + +@end itemize + +@vindex BASEFILENAME_LENGTH +Another rule, that only holds for filenames, is that base filenames +are truncated to 245 characters, to allow for an extension to be +appended and still comply with the 255-character limit which is common +to many filesystems. Although technically this can be changed with +the @code{BASEFILENAME_LENGTH} customization variable (@pxref{Other +Customization Variables}), doing so would make cross-manual references +to such nodes invalid. + +Any directory part in the filename argument of the source cross +reference command is ignored. Thus, @code{@@xref@{,,,../foo@}} and +@code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name. This +is because any such attempted hardwiring of the directory is very +unlikely to be useful for both Info and HTML output. + +Finally, the @var{target} part is always the expanded node name. + +Whether the present manual is split or mono is determined by user +option; @command{makeinfo} defaults to split, with the +@option{--no-split} option overriding this. + +Whether the referent manual is split or mono, however, is another bit +of the external information (@pxref{HTML Xref Configuration}). By +default, @command{makeinfo} uses the same form of the referent manual +as the present manual. + +Thus, there can be a mismatch between the format of the referent +manual that the generating software assumes, and the format it's +actually present in. @xref{HTML Xref Mismatch}. + + +@node HTML Xref Node Name Expansion +@subsection HTML Cross-reference Node Name Expansion +@cindex HTML cross-reference node name expansion +@cindex node name expansion, in HTML cross-references +@cindex expansion, of node names in HTML cross-references + +As mentioned in the previous section, the key part of the HTML cross +reference algorithm is the conversion of node names in the Texinfo +source into strings suitable for XHTML identifiers and filenames. The +restrictions are similar for each: plain ASCII letters, numbers, and +the @samp{-} and @samp{_} characters are all that can be used. +(Although HTML anchors can contain most characters, XHTML is more +restrictive.) + +Cross-references in Texinfo can refer either to nodes or anchors +(@pxref{@code{@@anchor}}). However, anchors are treated identically +to nodes in this context, so we'll continue to say ``node'' names for +simplicity. + +A special exception: the Top node (@pxref{The Top Node}) is always +mapped to the file @file{index.html}, to match web server software. +However, the HTML @emph{target} is @samp{Top}. Thus (in the split case): + +@example +@@xref@{Top,,, emacs, The GNU Emacs Manual@}. +@result{} <a href="emacs/index.html#Top"> +@end example + +@enumerate +@item +The standard ASCII letters (a-z and A-Z) are not modified. All other +characters may be changed as specified below. + +@item +The standard ASCII numbers (0-9) are not modified except when a number +is the first character of the node name. In that case, see below. + +@item +Multiple consecutive space, tab and newline characters are transformed +into just one space. (It's not possible to have newlines in node +names with the current implementation, but we specify it anyway, just +in case.) + +@item +Leading and trailing spaces are removed. + +@item +After the above has been applied, each remaining space character is +converted into a @samp{-} character. + +@item +Other ASCII 7-bit characters are transformed into @samp{_00@var{xx}}, +where @var{xx} is the ASCII character code in (lowercase) hexadecimal. +This includes @samp{_}, which is mapped to @samp{_005f}. + +@item +If the node name does not begin with a letter, the literal string +@samp{g_t} is prefixed to the result. (Due to the rules above, that +string can never occur otherwise; it is an arbitrary choice, standing +for ``GNU Texinfo''.) This is necessary because XHTML requires that +identifiers begin with a letter. + +@end enumerate + +For example: + +@example +@@node A node --- with _'% +@result{} A-node-_002d_002d_002d-with-_005f_0027_0025 +@end example + +Example translations of common characters: + +@itemize @bullet +@item @samp{_} @result{} @samp{_005f} +@item @samp{-} @result{} @samp{_002d} +@item @samp{A node} @result{} @samp{A-node} +@end itemize + +On case-folding computer systems, nodes differing only by case will be +mapped to the same file. In particular, as mentioned above, Top +always maps to the file @file{index.html}. Thus, on a case-folding +system, Top and a node named `Index' will both be written to +@file{index.html}. Fortunately, the targets serve to distinguish +these cases, since HTML target names are always case-sensitive, +independent of operating system. + + +@node HTML Xref Command Expansion +@subsection HTML Cross-reference Command Expansion +@cindex HTML cross-reference command expansion + +Node names may contain @@-commands (@pxref{Node Line Requirements}). +This section describes how they are handled. + +First, comments are removed. + +Next, any @code{@@value} commands (@pxref{@code{@@set @@value}}) and +macro invocations (@pxref{Invoking Macros}) are fully expanded. + +Then, for the following commands, the command name and braces are removed, +and the text of the argument is recursively transformed: + +@example +@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless +@@emph @@env @@file @@i @@indicateurl @@kbd @@key +@@samp @@sansserif @@sc @@slanted @@strong @@sub @@sup +@@t @@U @@var @@verb @@w +@end example + +@noindent For @code{@@sc}, any letters are capitalized. + +In addition, the following commands are replaced by constant text, as +shown below. If any of these commands have non-empty arguments, as in +@code{@@TeX@{bad@}}, it is an error, and the result is unspecified. +In this table, `(space)' means a space character and `(nothing)' means +the empty string. The notation `U+@var{hhhh}' means Unicode code +point @var{hhhh} (in hex, as usual). + +There are further transformations of many of these expansions to yield +the final file or other target name, such as space characters to +@samp{-}, etc., according to the other rules. + +@multitable @columnfractions .3 .5 +@item @code{@@(newline)} @tab (space) +@item @code{@@(space)} @tab (space) +@item @code{@@(tab)} @tab (space) +@item @code{@@!} @tab @samp{!} +@item @code{@@*} @tab (space) +@item @code{@@-} @tab (nothing) +@item @code{@@.} @tab @samp{.} +@item @code{@@:} @tab (nothing) +@item @code{@@?} @tab @samp{?} +@item @code{@@@@} @tab @samp{@@} +@item @code{@@@{} @tab @samp{@{} +@item @code{@@@}} @tab @samp{@}} +@item @code{@@LaTeX} @tab @samp{LaTeX} +@item @code{@@TeX} @tab @samp{TeX} +@item @code{@@arrow} @tab U+2192 +@item @code{@@bullet} @tab U+2022 +@item @code{@@comma} @tab @samp{,} +@item @code{@@copyright} @tab U+00A9 +@item @code{@@dots} @tab U+2026 +@item @code{@@enddots} @tab @samp{...} +@item @code{@@equiv} @tab U+2261 +@item @code{@@error} @tab @samp{error-->} +@item @code{@@euro} @tab U+20AC +@item @code{@@exclamdown} @tab U+00A1 +@item @code{@@expansion} @tab U+21A6 +@item @code{@@geq} @tab U+2265 +@item @code{@@leq} @tab U+2264 +@item @code{@@minus} @tab U+2212 +@item @code{@@ordf} @tab U+00AA +@item @code{@@ordm} @tab U+00BA +@item @code{@@point} @tab U+2605 +@item @code{@@pounds} @tab U+00A3 +@item @code{@@print} @tab U+22A3 +@item @code{@@questiondown} @tab U+00BF +@item @code{@@registeredsymbol} @tab U+00AE +@item @code{@@result} @tab U+21D2 +@item @code{@@textdegree} @tab U+00B0 +@item @code{@@tie} @tab (space) +@end multitable + +Quotation mark @@-commands (@code{@@quotedblright@{@}} and the like), +are likewise replaced by their Unicode values. Normal quotation +@emph{characters} (e.g., ASCII ` and ') are not altered. +@xref{Inserting Quotation Marks}. + +Any @code{@@acronym}, @code{@@abbr}, @code{@@email}, and +@code{@@image} commands are replaced by their first argument. (For +these commands, all subsequent arguments are optional, and ignored +here.) @xref{@code{@@acronym}}, and @ref{@code{@@email}}, and @ref{Images}. + +Accents are handled according to the next section. + +Any other command is an error, and the result is unspecified. + + +@node HTML Xref 8-bit Character Expansion +@subsection HTML Cross-reference 8-bit Character Expansion +@cindex HTML cross-reference 8-bit character expansion +@cindex 8-bit characters, in HTML cross-references +@cindex Expansion of 8-bit characters in HTML cross-references +@cindex Transliteration of 8-bit characters in HTML cross-references + +Usually, characters other than plain 7-bit ASCII are transformed into +the corresponding Unicode code point(s) in Normalization Form@tie{}C, +which uses precomposed characters where available. (This is the +normalization form recommended by the W3C and other bodies.) This +holds when that code point is @code{0xffff} or less, as it almost +always is. + +These will then be further transformed by the rules above into the +string @samp{_@var{hhhh}}, where @var{hhhh} is the code point in hex. + +For example, combining this rule and the previous section: + +@example +@@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@} +@result{} A-TeX-B_0306-_2605_002e_002e_002e +@end example + +Notice: 1)@tie{}@code{@@enddots} expands to three periods which in +turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B' +with a breve accent, which does not exist as a pre-accented Unicode +character, therefore expands to @samp{B_0306} (B with combining +breve). + +When the Unicode code point is above @code{0xffff}, the transformation +is @samp{__@var{xxxxxx}}, that is, two leading underscores followed by +six hex digits. Since Unicode has declared that their highest code +point is @code{0x10ffff}, this is sufficient. (We felt it was better +to define this extra escape than to always use six hex digits, since +the first two would nearly always be zeros.) + +This method works fine if the node name consists mostly of ASCII +characters and contains only few 8-bit ones. But if the document is +written in a language whose script is not based on the Latin alphabet +(for example, Ukrainian), it will create file names consisting almost +entirely of @samp{_@var{xxxx}} notations, which is inconvenient and +all but unreadable. To handle such cases, @command{makeinfo} offers +the @option{--transliterate-file-names} command line option. This +option enables @dfn{transliteration} of node names into ASCII +characters for the purposes of file name creation and referencing. +The transliteration is based on phonetic principles, which makes the +generated file names more easily understanable. + +@cindex Normalization Form C, Unicode +For the definition of Unicode Normalization Form@tie{}C, see Unicode +report UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many +related documents and implementations are available elsewhere on the +web. + + +@node HTML Xref Mismatch +@subsection HTML Cross-reference Mismatch +@cindex HTML cross-reference mismatch +@cindex Mismatched HTML cross-reference source and target + +As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating +software may need to guess whether a given manual being cross +referenced is available in split or monolithic form---and, inevitably, +it might guess wrong. However, when the @emph{referent} manual is +generated, it is possible to handle at least some mismatches. + +In the case where we assume the referent is split, but it is actually +available in mono, the only recourse would be to generate a +@file{manual/} subdirectory full of HTML files which redirect back to +the monolithic @file{manual.html}. Since this is essentially the same +as a split manual in the first place, it's not very appealing. + +On the other hand, in the case where we assume the referent is mono, +but it is actually available in split, it is possible to use +JavaScript to redirect from the putatively monolithic +@file{manual.html} to the different @file{manual/node.html} files. +Here's an example: + +@example +function redirect() @{ + switch (location.hash) @{ + case "#Node1": + location.replace("manual/Node1.html#Node1"); break; + case "#Node2" : + location.replace("manual/Node2.html#Node2"); break; + @dots{} + default:; + @} +@} +@end example + +Then, in the @code{<body>} tag of @file{manual.html}: + +@example +<body onLoad="redirect();"> +@end example + +Once again, this is something the software which generated the +@emph{referent} manual has to do in advance, it's not something the +software generating the cross-reference in the present manual can +control. + + +@node HTML Xref Configuration +@subsection HTML Cross-reference Configuration: @file{htmlxref.cnf} + +@pindex htmlxref.cnf +@cindex HTML cross-reference configuration +@cindex Cross-reference configuration, for HTML +@cindex Configuration, for HTML cross-manual references + +@command{makeinfo} reads a file named @file{htmlxref.cnf} to gather +information for cross-references to other manuals in HTML output. It +is looked for in the following directories: + +@table @file +@item ./ +(the current directory) + +@item ./.texinfo/ +(under the current directory) + +@item ~/.texinfo/ +(where @code{~} is the current user's home directory) + +@item @var{sysconfdir}/texinfo/ +(where @var{sysconfdir} is the system configuration directory +specified at compile-time, e.g., @file{/usr/local/etc}) + +@item @var{datadir}/texinfo/ +(likewise specified at compile time, e.g., @file{/usr/local/share}) +@end table + +All files found are used, with earlier entries overriding later ones. +The Texinfo distribution includes a default file which handles many +GNU manuals; it is installed in the last of the above directories, +i.e., @file{@var{datadir}/texinfo/htmlxref.cnf}. + +The file is line-oriented. Lines consisting only of whitespace are +ignored. Comments are indicated with a @samp{#} at the beginning of a +line, optionally preceded by whitespace. Since @samp{#} can occur in +urls (like almost any character), it does not otherwise start a +comment. + +Each non-blank non-comment line must be either a @dfn{variable +assignment} or @dfn{manual information}. + +A variable assignment line looks like this: + +@example +@var{varname} = @var{varvalue} +@end example + +Whitespace around the @samp{=} is optional and ignored. The +@var{varname} should consist of letters; case is significant. The +@var{varvalue} is an arbitrary string, continuing to the end of the +line. Variables are then referenced with @samp{$@{@var{varname}@}}; +variable references can occur in the @var{varvalue}. + +A manual information line looks like this: + +@example +@var{manual} @var{keyword} @var{urlprefix} +@end example + +@noindent +with @var{manual} the short identifier for a manual, @var{keyword} +being one of: @code{mono}, @code{node}, @code{section}, +@code{chapter}, and @var{urlprefix} described below. Variable +references can occur only in the @var{urlprefix}. For example (used +in the canonical @file{htmlxref.cnf}): + +@smallexample +G = http://www.gnu.org +GS = $@{G@}/software +hello mono $@{GS@}/hello/manual/hello.html +hello chapter $@{GS@}/hello/manual/html_chapter/ +hello section $@{GS@}/hello/manual/html_section/ +hello node $@{GS@}/hello/manual/html_node/ +@end smallexample + +@cindex monolithic manuals, for HTML cross-references +If the keyword is @code{mono}, @var{urlprefix} gives the host, +directory, and file name for @var{manual} as one monolithic file. + +@cindex split manuals, for HTML cross-references +If the keyword is @code{node}, @code{section}, or @code{chapter}, +@var{urlprefix} gives the host and directory for @var{manual} split +into nodes, sections, or chapters, respectively. + +When available, @command{makeinfo} will use the ``corresponding'' +value for cross-references between manuals. That is, when generating +monolithic output (@option{--no-split}), the @code{mono} url will be +used, when generating output that is split by node, the @code{node} +url will be used, etc. However, if a manual is not available in that +form, anything that is available can be used. Here is the search +order for each style: + +@smallexample +node @result{} node, section, chapter, mono +section @result{} section, chapter, node, mono +chapter @result{} chapter, section, node, mono +mono @result{} mono, chapter, section, node +@end smallexample + +@opindex --node-files@r{, and HTML cross-references} +These section- and chapter-level cross-manual references can succeed +only when the target manual was created using @option{--node-files}; +this is the default for split output. + +If you have additions or corrections to the @file{htmlxref.cnf} +distributed with Texinfo, please email @email{bug-texinfo@@gnu.org} as +usual. You can get the latest version from +@url{http://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}. + + +@node HTML Xref Link Preservation +@subsection HTML Cross-reference Link Preservation: @var{manual}@file{-noderename.cnf} + +@pindex noderename.cnf +@pindex @var{manual}-noderename.cnf +@cindex HTML cross-reference link preservation +@cindex Preserving HTML links to old nodes +@cindex Old nodes, preserving links to +@cindex Renaming nodes, and preserving links +@cindex Links, preserving to renamed nodes +@cindex Node renaming, and preserving links + +Occasionally changes in a program require removing (or renaming) nodes +in the manual in order to have the best documentation. Given the +nature of the web, however, links may exist anywhere to such a removed +node (renaming appears the same as removal for this purpose), and it's +not ideal for those links to simply break. + +The preferred approach to preserving links to deleted or renamed nodes +is to use anchors (@pxref{@code{@@anchor}}), as this works with all +output formats, including Info. +However, Texinfo provides an alternative method to do this for HTML +output via a separate file which specifes old +node names and the new nodes to which the old names should be +redirected. +This method is deprecated, and support for these files will be removed +in future Texinfo releases. It is specific to HTML and supporting +@@-commands in node names in these files in practice complicates the +implementation in @command{texi2any}. + +@vindex RENAMED_NODES_FILE +The @dfn{renamed nodes file} is named +@var{manual}@file{-noderename.cnf}, where +@var{manual} is the base name of the manual. +For example, the manual +@file{texinfo.texi} would be supplemented by a file +@file{texinfo-noderename}.cnf. (This name can be overridden by +setting the @file{RENAMED_NODES_FILE} customization variable; +@pxref{Customization Variables}). + +The file is read in pairs of lines, as follows: + +@example +@var{old-node-name} +@@@@@{@} @var{new-node-name} +@end example + +The usual conversion from Texinfo node names to HTML names is applied; +see this entire section for details (@pxref{HTML Xref}). The unusual +@samp{@@@@@{@}} separator is used because it is not a valid Texinfo +construct, so can't appear in the node names. + +The effect is that @command{makeinfo} generates a redirect from +@var{old-node-name} to @var{new-node-name} when producing HTML output. +Thus, external links to the old node are preserved. + +Lines consisting only of whitespace are ignored. Comments are +indicated with a @samp{@@c} at the beginning of a line, optionally +preceded by whitespace. + + +@node @@-Command Details +@appendix @@-Command Details + +Here are the details of @@-commands: information about their syntax, a +list of commands, and information about where commands can appear. + +@node Command Syntax +@section @@-Command Syntax +@cindex @@-command syntax +@cindex Syntax, of @@-commands +@cindex Command syntax + +Texinfo has the following types of @@-command: + +@table @asis +@item 1. Brace commands +These commands start with @@ followed by a letter or a word, followed by an +argument within braces. For example, the command @code{@@dfn} indicates +the introductory or defining use of a term; it is used as follows: @samp{In +Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.} + +@item 2. Line commands +These commands occupy an entire line. The line starts with @@, +followed by the name of the command (a word); for example, @code{@@center} +or @code{@@cindex}. If no argument is needed, the word is followed by +the end of the line. If there is an argument, it is separated from +the command name by a space. Braces are not used. + +@item 3. Block commands +These commands are written at the start of a line, with general text on +following lines, terminated by a matching @code{@@end} command on a +line of its own. For example, @code{@@example}, then the lines of a +coding example, then @code{@@end example}. Some of these block commands +take arguments as line commands do; for example, @code{@@enumerate A} +opening an environment terminated by @code{@@end enumerate}. Here +@samp{A} is the argument. + +@item 4. Symbol insertion commands with no arguments +These commands start with @@ followed by a word followed by a +left and right- brace. These commands insert special symbols in +the document; they do not take arguments. Some examples: +@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} +@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', and +@code{@@bullet@{@}} @result{} @samp{@bullet{}}. + +@item 5. Non-alphabetic commands +The names of commands in all of the above categories consist of +alphabetic characters, almost entirely in lower-case. Unlike those, the +non-alphabetic commands commands consist of an @@ followed by a +punctuation mark or other character that is not part of the Latin +alphabet. Non-alphabetic commands are almost always part of text +within a paragraph. The non-alphabetic commands include @code{@@@@}, +@code{@@@{}, @code{@@@}}, @code{@@.}, @code{@@@kbd{SPACE}}, and most of +the accent commands. + +@item 6. Miscellaneous commands +There are a handful of commands that don't fit into any of the above +categories; for example, the obsolete command @code{@@refill}, which is +always used at the end of a paragraph immediately following the final +period or other punctuation character. @code{@@refill} takes no +argument and does not require braces. Likewise, @code{@@tab} used in a +@code{@@multitable} block does not take arguments, and is not followed +by braces. +@end table + +@cindex Braces and argument syntax +Thus, the alphabetic commands fall into classes that have +different argument syntaxes. You cannot tell to which class a command +belongs by the appearance of its name, but you can tell by the +command's meaning: if the command stands for a glyph, it is in +class 4 and does not require an argument; if it makes sense to use the +command among other text as part of a paragraph, the command +is in class 1 and must be followed by an argument in braces. The +non-alphabetic commands, such as @code{@@:}, are exceptions to the +rule; they do not need braces. + +The purpose of having different syntax for commands is to make Texinfo +files easier to read, and also to help the GNU Emacs paragraph and +filling commands work properly. + + +@node Command List +@section @@-Command List +@cindex Alphabetical @@-command list +@cindex List of @@-commands +@cindex @@-command list +@cindex Reference to @@-commands + +Here is an alphabetical list of the @@-commands in Texinfo. Square +brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, +@samp{@dots{}}, indicates repeated text. + +@table @code +@item @@@var{whitespace} +An @code{@@} followed by a space, tab, or newline produces a normal, +stretchable, interword space. @xref{Multiple Spaces}. + +@item @@! +Produce an exclamation point that ends a sentence (usually after an +end-of-sentence capital letter). @xref{Ending a Sentence}. + +@item @@" +@itemx @@' +Generate an umlaut or acute accent, respectively, over the next +character, as in @"o and @'o. @xref{Inserting Accents}. + +@item @@& +@itemx @@ampchar@{@} +Generate an ampersand. @xref{Inserting an Ampersand}. + +@item @@* +Force a line break. @xref{Line Breaks}. + +@item @@,@{@var{c}@} +Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting +Accents}. + +@item @@- +Insert a discretionary hyphenation point. @xref{@code{@@- @@hyphenation}}. + +@item @@. +Produce a period that ends a sentence (usually after an +end-of-sentence capital letter). @xref{Ending a Sentence}. + +@item @@/ +Produces no output, but allows a line break. @xref{Line Breaks}. + +@item @@: +Tell @TeX{} to refrain from inserting extra whitespace after an +immediately preceding period, question mark, exclamation mark, or +colon, as @TeX{} normally would. @xref{Not Ending a Sentence}. + +@item @@= +Generate a macron (bar) accent over the next character, as in @=o. +@xref{Inserting Accents}. + +@item @@? +Produce a question mark that ends a sentence (usually after an +end-of-sentence capital letter). @xref{Ending a Sentence}. + +@item @@@@ +@itemx @@atchar@{@} +Insert an at sign, @samp{@@}. @xref{Inserting an Atsign}. + +@item @@\ +@itemx @@backslashchar@{@} +Insert a backslash, @samp{\}; @code{@@backslashchar@{@}} works +anywhere, while @code{@@\} works only inside @code{@@math}. +@xref{Inserting a Backslash}, and @ref{Inserting Math}. + +@item @@^ +@itemx @@` +Generate a circumflex (hat) or grave accent, respectively, over the next +character, as in @^o and @`e. +@xref{Inserting Accents}. + +@item @@@{ +@itemx @@lbracechar@{@} +Insert a left brace, @samp{@{}. @xref{Inserting Braces}. + +@item @@@} +@itemx @@rbracechar@{@} +Insert a right brace, @samp{@}}. @xref{Inserting Braces}. + +@item @@~ +Generate a tilde accent over the next character, as in @~N. +@xref{Inserting Accents}. + +@item @@AA@{@} +@itemx @@aa@{@} +Generate the uppercase and lowercase Scandinavian A-ring letters, +respectively: @AA{}, @aa{}. @xref{Inserting Accents}. + +@item @@abbr@{@var{abbreviation}@} +Indicate a general abbreviation, such as `Comput.'. +@xref{@code{@@abbr}}. + +@item @@acronym@{@var{acronym}@} +Indicate an acronym in all capital letters, such as `NASA'. +@xref{@code{@@acronym}}. + +@item @@AE@{@} +@itemx @@ae@{@} +Generate the uppercase and lowercase AE ligatures, respectively: +@AE{}, @ae{}. @xref{Inserting Accents}. + +@item @@afivepaper +Change page dimensions for the A5 paper size. @xref{A4 Paper}. + +@item @@afourlatex +@itemx @@afourpaper +@itemx @@afourwide +Change page dimensions for the A4 paper size. @xref{A4 Paper}. + +@item @@alias @var{new}=@var{existing} +Make the command @samp{@@@var{new}} a synonym for the existing command +@samp{@@@var{existing}}. @xref{@code{@@alias}}. + +@item @@allowcodebreaks @var{true-false} +Control breaking at @samp{-} and @samp{_} in @TeX{}. +@xref{@code{@@allowcodebreaks}}. + +@item @@anchor@{@var{name}@} +Define @var{name} as the current location for use as a cross-reference +target. @xref{@code{@@anchor}}. + +@item @@appendix @var{title} +Begin an appendix. The title appears in the table of contents. In +Info, the title is underlined with asterisks. +@xref{@code{@@unnumbered @@appendix}}. + +@item @@appendixsec @var{title} +@itemx @@appendixsection @var{title} +Begin an appendix section within an appendix. The section title +appears in the table of contents. In Info, the title is underlined +with equal signs. @code{@@appendixsection} is a longer spelling of +the @code{@@appendixsec} command. @xref{@code{@@unnumberedsec +@@appendixsec @@heading}}. + +@item @@appendixsubsec @var{title} +Begin an appendix subsection. The title appears in the table of +contents. In Info, the title is underlined with hyphens. +@xref{@code{@@unnumberedsubsec @@appendixsubsec @@subheading}}. + +@item @@appendixsubsubsec @var{title} +Begin an appendix subsubsection. The title appears in the table of +contents. In Info, the title is underlined with periods. +@xref{@code{@@subsubsection}}. + +@item @@arrow@{@} +Generate a right arrow glyph: @samp{@arrow{}}. Used by default +for @code{@@click}. @xref{Click Sequences}. + +@item @@asis +Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to +print the table's first column without highlighting (``as is''). +@xref{@code{@@asis}}. + +@item @@author @var{author} +Typeset @var{author} flushleft and underline it. @xref{@code{@@title +@@subtitle @@author}}. + +@item @@b@{@var{text}@} +Set @var{text} in a @b{bold} font. No effect in Info. @xref{Fonts}. + +@item @@bullet@{@} +Generate a large round dot, @bullet{} (@samp{*} in Info). Often used +with @code{@@table}. @xref{@code{@@bullet}}. + +@item @@bye +Stop formatting a file. The formatters do not see anything in the +input file following @code{@@bye}. @xref{Ending a File}. + +@item @@c @var{comment} +Begin a comment in Texinfo. The rest of the line does not appear in +any output. A synonym for @code{@@comment}. @kbd{DEL} also +starts a comment. @xref{Comments}. + +@item @@caption +Define the full caption for a @code{@@float}. @xref{@code{@@caption +@@shortcaption}}. + +@item @@cartouche +Highlight an example or quotation by drawing a box with rounded +corners around it. Pair with @code{@@end cartouche}. No effect in +Info. @xref{@code{@@cartouche}}. + +@item @@center @var{line-of-text} +Center the line of text following the command. +@xref{@code{@@titlefont @@center @@sp}}. + +@item @@centerchap @var{line-of-text} +Like @code{@@chapter}, but centers the chapter title. @xref{@code{@@chapter}}. + +@item @@chapheading @var{title} +Print an unnumbered chapter-like heading, but omit from the table of +contents. In Info, the title is underlined with asterisks. +@xref{@code{@@majorheading @@chapheading}}. + +@item @@chapter @var{title} +Begin a numbered chapter. The chapter title appears in the table of +contents. In Info, the title is underlined with asterisks. +@xref{@code{@@chapter}}. + +@item @@cindex @var{entry} +Add @var{entry} to the index of concepts. @xref{Index Entries, , +Defining the Entries of an Index}. + +@item @@cite@{@var{reference}@} +Highlight the name of a book or other reference that has no companion +Info file. @xref{@code{@@cite}}. + +@item @@clear @var{flag} +Unset @var{flag}, preventing the Texinfo formatting commands from +formatting text between subsequent pairs of @code{@@ifset @var{flag}} +and @code{@@end ifset} commands, and preventing +@code{@@value@{@var{flag}@}} from expanding to the value to which +@var{flag} is set. @xref{@code{@@set @@clear @@value}}. + +@item @@click@{@} +Represent a single ``click'' in a GUI@. Used within +@code{@@clicksequence}. @xref{Click Sequences}. + +@item @@clicksequence@{@var{action} @@click@{@} @var{action}@} +Represent a sequence of clicks in a GUI@. @xref{Click Sequences}. + +@item @@clickstyle @@@var{cmd} +Execute @@@var{cmd} for each @code{@@click}; the default is +@code{@@arrow}. The usual following empty braces on @@@var{cmd} are +omitted. @xref{Click Sequences}. + +@item @@code@{@var{sample-code}@} +Indicate an expression, a syntactically complete token of a program, +or a program name. Unquoted in Info output. @xref{@code{@@code}}. + +@item @@codequotebacktick @var{on-off} +@itemx @@codequoteundirected @var{on-off} +Control output of @code{`} and @code{'} in code examples. +@xref{Inserting Quote Characters}. + +@item @@comma@{@} +Insert a comma `,' character; only needed when a literal comma would +be taken as an argument separator. @xref{Inserting a Comma}. + +@item @@command@{@var{command-name}@} +Indicate a command name, such as @command{ls}. @xref{@code{@@command}}. + +@item @@comment @var{comment} +Begin a comment in Texinfo. The rest of the line does not appear in +any output. A synonym for @code{@@c}. +@xref{Comments}. + +@item @@contents +Print a complete table of contents. Has no effect in Info, which uses +menus instead. @xref{Contents, , Generating a Table of Contents}. + +@item @@copying +Specify copyright holders and copying conditions for the document. Pair +with @code{@@end copying}. @xref{@code{@@copying}}. + +@item @@copyright@{@} +Generate the copyright symbol @copyright{}. +@xref{@code{@@copyright}}. + +@item @@defcodeindex @var{index-name} +Define a new index and its indexing command. Print entries in an +@code{@@code} font. @xref{New Indices, , Defining New Indices}. + +@item @@defcv @var{category} @var{class} @var{name} +@itemx @@defcvx @var{category} @var{class} @var{name} +Format a description for a variable associated with a class in +object-oriented programming. Takes three arguments: the category of +thing being defined, the class to which it belongs, and its name. +@xref{Definition Commands}. + +@item @@deffn @var{category} @var{name} @var{arguments}@dots{} +@itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{} +Format a description for a function, interactive command, or similar +entity that may take arguments. @code{@@deffn} takes as arguments the +category of entity being described, the name of this particular +entity, and its arguments, if any. @xref{Definition Commands}. + +@item @@defindex @var{index-name} +Define a new index and its indexing command. Print entries in a roman +font. @xref{New Indices, , Defining New Indices}. + +@item @@definfoenclose @var{newcmd}, @var{before}, @var{after} +Must be used within @code{@@ifinfo}; create a new command +@code{@@@var{newcmd}} for Info that marks text by enclosing it in +strings that precede and follow the text. +@xref{@code{@@definfoenclose}}. + +@item @@defivar @var{class} @var{instance-variable-name} +@itemx @@defivarx @var{class} @var{instance-variable-name} +Format a description for an instance variable in object-oriented +programming. The command is equivalent to @samp{@@defcv @{Instance +Variable@} @dots{}}. @xref{Definition Commands}. + +@item @@defmac @var{macroname} @var{arguments}@dots{} +@itemx @@defmacx @var{macroname} @var{arguments}@dots{} +Format a description for a macro; equivalent to @samp{@@deffn Macro +@dots{}}. @xref{Definition Commands}. + +@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{} +@itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{} +Format a description for a method in object-oriented programming; +equivalent to @samp{@@defop Method @dots{}}. @xref{Definition +Commands}. + +@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} +@itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{} +Format a description for an operation in object-oriented programming. +@code{@@defop} takes as arguments the name of the category of +operation, the name of the operation's class, the name of the +operation, and its arguments, if any. @xref{Definition Commands}, and +@ref{Abstract Objects}. + +@item @@defopt @var{option-name} +@itemx @@defoptx @var{option-name} +Format a description for a user option; equivalent to @samp{@@defvr +@{User Option@} @dots{}}. @xref{Definition Commands}. + +@item @@defspec @var{special-form-name} @var{arguments}@dots{} +@itemx @@defspecx @var{special-form-name} @var{arguments}@dots{} +Format a description for a special form; equivalent to @samp{@@deffn +@{Special Form@} @dots{}}. @xref{Definition Commands}. + +@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} +@itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{} +Format a description for a data type; its arguments are the category, +the name of the type (e.g., @samp{int}) , and then the names of +attributes of objects of that type. @xref{Definition Commands}, and +@ref{Data Types}. + +@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name} +@itemx @@deftypecvx @var{category} @var{class} @var{data-type} @var{name} +Format a description for a typed class variable in object-oriented programming. +@xref{Definition Commands}, and @ref{Abstract Objects}. + +@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} +@itemx @@deftypefnx @var{category} @var{data-type} @var{name} @var{arguments}@dots{} +Format a description for a function or similar entity that may take +arguments and that is typed. @code{@@deftypefn} takes as arguments the +category of entity being described, the type, the name of the +entity, and its arguments, if any. @xref{Definition Commands}. + +@item @@deftypefnnewline @var{on-off} +Specifies whether return types for @code{@@deftypefn} and similar are +printed on lines by themselves; default is off. @xref{Typed +Functions,, Functions in Typed Languages}. + +@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{} +@itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{} +Format a description for a function in a typed language. +The command is equivalent to @samp{@@deftypefn Function @dots{}}. +@xref{Definition Commands}. + +@item @@deftypeivar @var{class} @var{data-type} @var{variable-name} +@itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name} +Format a description for a typed instance variable in object-oriented +programming. @xref{Definition Commands}, and @ref{Abstract Objects}. + +@item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} +@itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} +Format a description for a typed method in object-oriented programming. +@xref{Definition Commands}. + +@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} +@itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} +Format a description for a typed operation in object-oriented programming. +@xref{Definition Commands}, and @ref{Abstract Objects}. + +@item @@deftypevar @var{data-type} @var{variable-name} +@itemx @@deftypevarx @var{data-type} @var{variable-name} +Format a description for a variable in a typed language. The command is +equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition +Commands}. + +@item @@deftypevr @var{category} @var{data-type} @var{name} +@itemx @@deftypevrx @var{category} @var{data-type} @var{name} +Format a description for something like a variable in a typed +language---an entity that records a value. Takes as arguments the +category of entity being described, the type, and the name of the +entity. @xref{Definition Commands}. + +@item @@defun @var{function-name} @var{arguments}@dots{} +@itemx @@defunx @var{function-name} @var{arguments}@dots{} +Format a description for a function; equivalent to +@samp{@@deffn Function @dots{}}. @xref{Definition Commands}. + +@item @@defvar @var{variable-name} +@itemx @@defvarx @var{variable-name} +Format a description for a variable; equivalent to @samp{@@defvr +Variable @dots{}}. @xref{Definition Commands}. + +@item @@defvr @var{category} @var{name} +@itemx @@defvrx @var{category} @var{name} +Format a description for any kind of variable. @code{@@defvr} takes +as arguments the category of the entity and the name of the entity. +@xref{Definition Commands}. + +@item @@detailmenu +Mark the (optional) detailed node listing in a master menu. +@xref{Master Menu Parts}. + +@item @@dfn@{@var{term}@} +Indicate the introductory or defining use of a term. @xref{@code{@@dfn}}. + +@item @@DH@{@} +@itemx @@dh@{@} +Generate the uppercase and lowercase Icelandic letter eth, respectively: +@DH{}, @dh{}. @xref{Inserting Accents}. + +@item @@dircategory @var{dirpart} +Specify a part of the Info directory menu where this file's entry should +go. @xref{Installing Dir Entries}. + +@item @@direntry +Begin the Info directory menu entry for this file. Pair with +@code{@@end direntry}. @xref{Installing Dir Entries}. + +@item @@display +Begin a kind of example. Like @code{@@example} (indent text, do not +fill), but do not select a new font. Pair with @code{@@end display}. +@xref{@code{@@display}}. + +@item @@dmn@{@var{dimension}@} +Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a +thin space before @var{dimension}. No effect in Info. +@xref{@code{@@dmn}}. + +@item @@docbook +Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw +Formatter Commands}. + +@item @@documentdescription +Set the document description text, included in the HTML output. Pair +with @code{@@end documentdescription}. @xref{@code{@@documentdescription}}. + +@item @@documentencoding @var{enc} +Declare the input encoding to be @var{enc}. +@xref{@code{@@documentencoding}}. + +@item @@documentlanguage @var{CC} +Declare the document language as the two-character ISO-639 abbreviation +@var{CC}. @xref{@code{@@documentlanguage}}. + +@item @@dotaccent@{@var{c}@} +Generate a dot accent over the character @var{c}, as in @dotaccent{o}. +@xref{Inserting Accents}. + +@item @@dotless@{@var{i-or-j}@} +Generate dotless i (`@dotless{i}') and dotless j (`@dotless{j}'). +@xref{Inserting Accents}. + +@item @@dots@{@} +Generate an ellipsis, @samp{@dots{}}. +@xref{@code{@@dots}}. + +@item @@email@{@var{address}[, @var{displayed-text}]@} +Indicate an electronic mail address. @xref{@code{@@email}}. + +@item @@emph@{@var{text}@} +Emphasize @var{text}, by using @emph{italics} where possible, and +enclosing in asterisks in Info. @xref{Emphasis, , Emphasizing Text}. + +@item @@end @var{environment} +Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting +Commands,,@@-commands}. + +@item @@enddots@{@} +Generate an end-of-sentence ellipsis, like this: @enddots{} +@xref{@code{@@dots}}. + +@item @@enumerate [@var{number-or-letter}] +Begin a numbered list, using @code{@@item} for each entry. +Optionally, start list with @var{number-or-letter}. Pair with +@code{@@end enumerate}. @xref{@code{@@enumerate}}. + +@item @@env@{@var{environment-variable}@} +Indicate an environment variable name, such as @env{PATH}. +@xref{@code{@@env}}. + +@item @@equiv@{@} +Indicate to the reader the exact equivalence of two forms with a +glyph: @samp{@equiv{}}. @xref{@code{@@equiv}}. + +@item @@error@{@} +Indicate to the reader with a glyph that the following text is +an error message: @samp{@error{}}. @xref{@code{@@error}}. + +@item @@errormsg@{@var{msg}@} +Report @var{msg} as an error to standard error, and exit unsuccessfully. +Texinfo commands within @var{msg} are expanded to plain text. +@xref{Conditionals}, and @ref{External Macro Processors}. + +@item @@euro@{@} +Generate the Euro currency sign. @xref{@code{@@euro}}. + +@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] +@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] +Specify page footings resp.@: headings for even-numbered (left-hand) +pages. @xref{Custom Headings, , +How to Make Your Own Headings}. + +@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] +@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] +Specify page footings resp.@: headings for every page. Not relevant to +Info. @xref{Custom Headings, , How to Make Your Own Headings}. + +@item @@example +Begin an example. Indent text, do not fill, and select fixed-width +font. Pair with @code{@@end example}. @xref{@code{@@example}}. + +@item @@exampleindent @var{indent} +Indent example-like environments by @var{indent} number of spaces +(perhaps 0). @xref{@code{@@exampleindent}}. + +@item @@exclamdown@{@} +Generate an upside-down exclamation point. @xref{Inserting Accents}. + +@item @@exdent @var{line-of-text} +Remove any indentation a line might have. @xref{@code{@@exdent}}. + +@item @@expansion@{@} +Indicate the result of a macro expansion to the reader with a special +glyph: @samp{@expansion{}}. @xref{@code{@@expansion}}. + +@item @@file@{@var{filename}@} +Highlight the name of a file, buffer, node, directory, etc. +@xref{@code{@@file}}. + +@item @@finalout +Prevent @TeX{} from printing large black warning rectangles beside +over-wide lines. @xref{Overfull hboxes}. + +@item @@findex @var{entry} +Add @var{entry} to the index of functions. @xref{Index Entries, , +Defining the Entries of an Index}. + +@item @@firstparagraphindent @var{word} +Control indentation of the first paragraph after section headers +according to @var{word}, one of `none' or `insert'. +@xref{@code{@@firstparagraphindent}}. + +@item @@float +Environment to define floating material. Pair with @code{@@end float}. +@xref{Floats}. + +@item @@flushleft +@itemx @@flushright +Do not fill text; left (right) justify every line while leaving the +right (left) end ragged. Leave font as is. Pair with @code{@@end +flushleft} (@code{@@end flushright}). @xref{@code{@@flushleft +@@flushright}}. + +@item @@fonttextsize @var{10-11} +Change the size of the main body font in the @TeX{} output. +@xref{Fonts}. + +@item @@footnote@{@var{text-of-footnote}@} +Enter a footnote. Footnote text is printed at the bottom of the page +by @TeX{}; Info may format in either `End' node or `Separate' node style. +@xref{Footnotes}. + +@item @@footnotestyle @var{style} +Specify an Info file's footnote style, either @samp{end} for the end +node style or @samp{separate} for the separate node style. +@xref{Footnotes}. + +@item @@format +Begin a kind of example. Like @code{@@display}, but do not indent. +Pair with @code{@@end format}. @xref{@code{@@example}}. + +@item @@frenchspacing @var{on-off} +Control spacing after punctuation. @xref{@code{@@frenchspacing}}. + +@item @@ftable @var{formatting-command} +Begin a two-column table, using @code{@@item} for each entry. +Automatically enter each of the items in the first column into the +index of functions. Pair with @code{@@end ftable}. The same as +@code{@@table}, except for indexing. @xref{@code{@@ftable @@vtable}}. + +@item @@geq@{@} +Generate a greater-than-or-equal sign, `@geq{}'. @xref{@code{@@geq @@leq}}. + +@item @@group +Disallow page breaks within following text. Pair with @code{@@end +group}. Ignored in Info. @xref{@code{@@group}}. + +@item @@guillemetleft@{@} +@itemx @@guillemetright@{@} +@item @@guillemotleft@{@} +@itemx @@guillemotright@{@} +@itemx @@guilsinglleft@{@} +@itemx @@guilsinglright@{@} +Double and single angle quotation marks: @guillemetleft{} +@guillemetright{} @guilsinglleft{} @guilsinglright{}. +@code{@@guillemotleft} and @code{@@guillemotright} are synonyms for +@code{@@guillemetleft} and @code{@@guillemetright}. @xref{Inserting +Quotation Marks}. + +@item @@H@{@var{c}@} +Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}. + +@item @@hashchar@{@} +Insert a hash `#' character; only needed when a literal hash would +introduce @code{#line} directive. @xref{Inserting a Hashsign}, and +@ref{External Macro Processors}. + +@item @@heading @var{title} +Print an unnumbered section-like heading, but omit from the table of +contents. In Info, the title is underlined with equal signs. +@xref{@code{@@unnumberedsec @@appendixsec @@heading}}. + +@item @@headings @var{on-off-single-double} +Turn page headings on or off, and/or specify single-sided or double-sided +page headings for printing. @xref{@code{@@headings}}. + +@item @@headitem +Begin a heading row in a multitable. @xref{Multitable Rows}. + +@item @@headitemfont@{@var{text}@} +Set @var{text} in the font used for multitable heading rows; mostly +useful in multitable templates. @xref{Multitable Rows}. + +@item @@html +Enter HTML completely. Pair with @code{@@end html}. @xref{Raw +Formatter Commands}. + +@item @@hyphenation@{@var{hy-phen-a-ted words}@} +Explicitly define hyphenation points. @xref{@code{@@- @@hyphenation}}. + +@item @@i@{@var{text}@} +Set @var{text} in an @i{italic} font. No effect in Info. @xref{Fonts}. + +@item @@ifclear @var{txivar} +If the Texinfo variable @var{txivar} is not set, format the following +text. Pair with @code{@@end ifclear}. @xref{@code{@@set @@clear +@@value}}. + +@item @@ifcommanddefined @var{txicmd} +@itemx @@ifcommandnotdefined @var{txicmd} +If the Texinfo code @samp{@@@var{txicmd}} is (not) defined, format the +follow text. Pair with the corresponding @code{@@end ifcommand...}. +@xref{Testing for Texinfo Commands}. + +@item @@ifdocbook +@itemx @@ifhtml +@itemx @@ifinfo +Begin text that will appear only in the given output format. +@code{@@ifinfo} output appears in both Info and (for historical +compatibility) plain text output. Pair with @code{@@end ifdocbook} +resp.@: @code{@@end ifhtml} resp.@: @code{@@end ifinfo}. +@xref{Conditionals}. + +@item @@ifnotdocbook +@itemx @@ifnothtml +@itemx @@ifnotplaintext +@itemx @@ifnottex +@itemx @@ifnotxml +Begin text to be ignored in one output format but not the others. +@code{@@ifnothtml} text is omitted from HTML output, etc. Pair with +the corresponding @code{@@end ifnot@var{format}}. +@xref{Conditionals}. + +@item @@ifnotinfo +Begin text to appear in output other than Info and (for historical +compatibility) plain text. Pair with @code{@@end ifnotinfo}. +@xref{Conditionals}. + +@item @@ifplaintext +Begin text that will appear only in the plain text output. +Pair with @code{@@end ifplaintext}. @xref{Conditionals}. + +@item @@ifset @var{txivar} +If the Texinfo variable @var{txivar} is set, format the following +text. Pair with @code{@@end ifset}. @xref{@code{@@set @@clear +@@value}}. + +@item @@iftex +Begin text to appear only in the @TeX{} output. Pair with @code{@@end +iftex}. @xref{Conditionals, , Conditionally Visible Text}. + +@item @@ifxml +Begin text that will appear only in the XML output. Pair with +@code{@@end ifxml}. @xref{Conditionals}. + +@item @@ignore +Begin text that will not appear in any output. Pair with @code{@@end +ignore}. @xref{Comments, , Comments and Ignored Text}. + +@item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@} +Include graphics image in external @var{filename} scaled to the given +@var{width} and/or @var{height}, using @var{alt} text and looking for +@samp{@var{filename}.@var{ext}} in HTML@. @xref{Images}. + +@item @@include @var{filename} +Read the contents of Texinfo source file @var{filename}. @xref{Include Files}. + +@item @@indent +Insert paragraph indentation. @xref{@code{@@indent}}. + +@item @@indentedblock +Indent a block of arbitary text on the left. Pair with @code{@@end +indentedblock}. @xref{@code{@@indentedblock}}. + +@item @@indicateurl@{@var{indicateurl}@} +Indicate text that is a uniform resource locator for the World Wide +Web. @xref{@code{@@indicateurl}}. + +@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@} +Make a cross-reference to an Info file for which there is no printed +manual. @xref{@code{@@inforef}}. + +@item @@inlinefmt@{@var{fmt}, @var{text}@} +Insert @var{text} only if the output format is @var{fmt}. +@xref{Inline Conditionals}. + +@item @@inlinefmtifelse@{@var{fmt}, @var{text}, @var{else-text}@} +Insert @var{text} if the output format is @var{fmt}, else @var{else-text}. + +@item @@inlineifclear@{@var{var}, @var{text}@} +@itemx @@inlineifset@{@var{var}, @var{text}@} +Insert @var{text} only if the Texinfo variable @var{var} is (not) set. + +@item @@inlineraw@{@var{fmt}, @var{raw-text}@} +Insert @var{text} as in a raw conditional, only if the output format +is @var{fmt}. + +@item \input @var{macro-definitions-file} +Use the specified macro definitions file. This command is used only +in the first line of a Texinfo file to cause @TeX{} to make use of the +@file{texinfo} macro definitions file. The @code{\} in @code{\input} +is used instead of an @code{@@} because @TeX{} does not recognize +@code{@@} until after it has read the definitions file. @xref{Texinfo +File Header}. + +@item @@insertcopying +Insert the text previously defined with the @code{@@copying} +environment. @xref{@code{@@insertcopying}}. + +@item @@item +Indicate the beginning of a marked paragraph for @code{@@itemize} and +@code{@@enumerate}; indicate the beginning of the text of a first column +entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. +@xref{Lists and Tables}. + +@item @@itemize @var{mark-generating-character-or-command} +Begin an unordered list: indented paragraphs with a mark, such as +@code{@@bullet}, inside the left margin at the beginning of each item. +Pair with @code{@@end itemize}. @xref{@code{@@itemize}}. + +@item @@itemx +Like @code{@@item} but do not generate extra vertical space above the +item text. Thus, when several items have the same description, use +@code{@@item} for the first and @code{@@itemx} for the others. +@xref{@code{@@itemx}}. + +@item @@kbd@{@var{keyboard-characters}@} +Indicate characters of input to be typed by users. @xref{@code{@@kbd}}. + +@item @@kbdinputstyle @var{style} +Specify when @code{@@kbd} should use a font distinct from +@code{@@code} according to @var{style}: @code{code}, @code{distinct}, +@code{example}. @xref{@code{@@kbd}}. + +@item @@key@{@var{key-name}@} +Indicate the name of a key on a keyboard. @xref{@code{@@key}}. + +@item @@kindex @var{entry} +Add @var{entry} to the index of keys. +@xref{Index Entries, , Defining the Entries of an Index}. + +@item @@L@{@} +@itemx @@l@{@} +Generate the uppercase and lowercase Polish suppressed-L letters, +respectively: @L{}, @l{}. + +@item @@LaTeX@{@} +Generate the @LaTeX{} logo. @xref{@code{@@TeX @@LaTeX}}. + +@item @@leq@{@} +Generate a less-than-or-equal sign, `@leq{}'. @xref{@code{@@geq @@leq}}. + +@item @@lisp +Begin an example of Lisp code. Indent text, do not fill, and select +fixed-width font. Pair with @code{@@end lisp}. @xref{@code{@@lisp}}. + +@item @@listoffloats +Produce a table-of-contents-like listing of @code{@@float}s. +@xref{@code{@@listoffloats}}. + +@item @@lowersections +Change subsequent chapters to sections, sections to subsections, and so +on. @xref{Raise/lower sections, , @code{@@raisesections} and +@code{@@lowersections}}. + +@item @@macro @var{macroname} @{@var{params}@} +Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}. +Pair with @code{@@end macro}. @xref{Defining Macros}. + +@item @@majorheading @var{title} +Print an unnumbered chapter-like heading, but omit from the table of +contents. This generates more vertical whitespace before the heading +than the @code{@@chapheading} command. @xref{@code{@@majorheading +@@chapheading}}. + +@item @@math@{@var{mathematical-expression}@} +Format a mathematical expression. @xref{Inserting Math}. + +@item @@menu +Mark the beginning of a menu of nodes. No effect in a printed manual. +Pair with @code{@@end menu}. @xref{Menus}. + +@item @@minus@{@} +Generate a minus sign, `@minus{}'. @xref{@code{@@minus}}. + +@item @@multitable @var{column-width-spec} +Begin a multi-column table. Begin each row with @code{@@item} or +@code{@@headitem}, and separate columns with @code{@@tab}. Pair with +@code{@@end multitable}. @xref{Multitable Column Widths}. + +@item @@need @var{n} +Start a new page in a printed manual if fewer than @var{n} mils +(thousandths of an inch) remain on the current page. +@xref{@code{@@need}}. + +@item @@node @var{name}, @var{next}, @var{previous}, @var{up} +Begin a new node. @xref{Writing a Node}. + +@item @@noindent +Prevent text from being indented as if it were a new paragraph. +@xref{@code{@@noindent}}. + +@item @@novalidate +Suppress validation of node references and omit creation of auxiliary +files with @TeX{}. Use before any sectioning or cross-reference +commands. @xref{Pointer Validation}. + +@item @@O@{@} +@itemx @@o@{@} +Generate the uppercase and lowercase O-with-slash letters, respectively: +@O{}, @o{}. + +@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] +@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] +Specify page footings resp.@: headings for odd-numbered (right-hand) +pages. @xref{Custom Headings, , +How to Make Your Own Headings}. + +@item @@OE@{@} +@itemx @@oe@{@} +Generate the uppercase and lowercase OE ligatures, respectively: +@OE{}, @oe{}. @xref{Inserting Accents}. + +@item @@ogonek@{@var{c}@} +Generate an ogonek diacritic under the next character, as in +@ogonek{a}. @xref{Inserting Accents}. + +@item @@option@{@var{option-name}@} +Indicate a command-line option, such as @option{-l} or +@option{--help}. @xref{@code{@@option}}. + +@item @@ordf@{@} +@itemx @@ordm@{@} +Generate the feminine and masculine Spanish ordinals, respectively: +@ordf{}, @ordm{}. @xref{Inserting Accents}. + +@item @@page +Start a new page in a printed manual. No effect in Info. +@xref{@code{@@page}}. + +@item @@pagesizes [@var{width}][, @var{height}] +Change page dimensions. @xref{pagesizes}. + +@item @@paragraphindent @var{indent} +Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve +source file indentation if @var{indent} is @code{asis}. +@xref{@code{@@paragraphindent}}. + +@item @@part @var{title} +Begin a group of chapters or appendixes; included in the tables of +contents and produces a page of its own in printed output. +@xref{@code{@@part}}. + +@item @@pindex @var{entry} +Add @var{entry} to the index of programs. @xref{Index Entries, , Defining +the Entries of an Index}. + +@item @@point@{@} +Indicate the position of point in a buffer to the reader with a glyph: +@samp{@point{}}. @xref{@code{@@point}}. + +@item @@pounds@{@} +Generate the pounds sterling currency sign. +@xref{@code{@@pounds}}. + +@item @@print@{@} +Indicate printed output to the reader with a glyph: @samp{@print{}}. +@xref{@code{@@print}}. + +@item @@printindex @var{index-name} +Generate the alphabetized index for @var{index-name} (using two +columns in a printed manual). @xref{Printing Indices & Menus}. + +@item @@pxref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} +Make a reference that starts with a lowercase `see' in a printed +manual. Use within parentheses only. Only the first argument is +mandatory. @xref{@code{@@pxref}}. + +@item @@questiondown@{@} +Generate an upside-down question mark. @xref{Inserting Accents}. + +@item @@quotation +Narrow the margins to indicate text that is quoted from another work. +Takes optional argument specifying prefix text, e.g., an author name. +Pair with @code{@@end quotation}. @xref{@code{@@quotation}}. + +@item @@quotedblleft@{@} +@itemx @@quotedblright@{@} +@itemx @@quoteleft@{@} +@itemx @@quoteright@{@} +@itemx @@quotedblbase@{@} +@itemx @@quotesinglbase@{@} +Produce various quotation marks: @quotedblleft{} @quotedblright{} +@quoteleft{} @quoteright{} @quotedblbase{} @quotesinglbase{}. +@xref{Inserting Quotation Marks}. + +@item @@r@{@var{text}@} +Set @var{text} in the regular @r{roman} font. No effect in Info. +@xref{Fonts}. + +@item @@raggedright +Fill text; left justify every line while leaving the right end ragged. +Leave font as is. Pair with @code{@@end raggedright}. No effect in +Info. @xref{@code{@@raggedright}}. + +@item @@raisesections +Change subsequent sections to chapters, subsections to sections, and so +on. @xref{Raise/lower sections}. + +@item @@ref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} +Make a plain reference that does not start with any special text. +Follow command with a punctuation mark. Only the first argument is +mandatory. @xref{@code{@@ref}}. + +@item @@refill +@findex refill +This command used to refill and indent the paragraph after all the +other processing has been done. It is no longer needed, since all +formatters now automatically refill as needed, but you may still see +it in the source to some manuals, as it does no harm. + +@item @@registeredsymbol@{@} +Generate the legal symbol @registeredsymbol{}. +@xref{@code{@@registeredsymbol}}. + +@item @@result@{@} +Indicate the result of an expression to the reader with a special +glyph: @samp{@result{}}. @xref{@code{@@result}}. + +@item @@ringaccent@{@var{c}@} +Generate a ring accent over the next character, as in @ringaccent{o}. +@xref{Inserting Accents}. + +@item @@samp@{@var{text}@} +Indicate a literal example of a sequence of characters, in general. +Quoted in Info output. @xref{@code{@@samp}}. + +@item @@sansserif@{@var{text}@} +Set @var{text} in a @sansserif{sans serif} font if possible. No +effect in Info. @xref{Fonts}. + +@item @@sc@{@var{text}@} +Set @var{text} in a small caps font in printed output, and uppercase +in Info. @xref{Smallcaps}. + +@item @@section @var{title} +Begin a section within a chapter. The section title appears in the +table of contents. In Info, the title is underlined with equal signs. +Within @code{@@chapter} and @code{@@appendix}, the section title is +numbered; within @code{@@unnumbered}, the section is unnumbered. +@xref{@code{@@section}}. + +@item @@set @var{txivar} [@var{string}] +Define the Texinfo variable @var{txivar}, optionally to the value +@var{string}. @xref{@code{@@set @@clear @@value}}. + +@item @@setchapternewpage @var{on-off-odd} +Specify whether chapters start on new pages, and if so, whether on +odd-numbered (right-hand) new pages. @xref{@code{@@setchapternewpage}}. + +@item @@setfilename @var{info-file-name} +Provide a name to be used for the output files. This command is ignored +for @TeX{} formatting. @xref{@code{@@setfilename}}. + +@item @@settitle @var{title} +Specify the title for page headers in a printed manual, and the +default document title for HTML @samp{<head>}. +@xref{@code{@@settitle}}. + +@item @@shortcaption +Define the short caption for a @code{@@float}. @xref{@code{@@caption +@@shortcaption}}. + +@item @@shortcontents +Print a short table of contents, with chapter-level entries only. Not +relevant to Info, which uses menus rather than tables of contents. +@xref{Contents, , Generating a Table of Contents}. + +@item @@shorttitlepage @var{title} +Generate a minimal title page. @xref{@code{@@titlepage}}. + +@item @@slanted@{@var{text}@} +Set @var{text} in a @slanted{slanted} font if possible. No effect +in Info. @xref{Fonts}. + +@item @@smallbook +Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format +rather than the regular 8.5 by 11 inch format. +@xref{@code{@@smallbook}}. Also, see @ref{@code{@@small@dots{}}}. + +@item @@smalldisplay +Begin a kind of example. Like @code{@@display}, but use a smaller +font size where possible. Pair with @code{@@end smalldisplay}. +@xref{@code{@@small@dots{}}}. + +@item @@smallexample +Begin an example. Like @code{@@example}, but use a smaller font size +where possible. Pair with @code{@@end smallexample}. +@xref{@code{@@small@dots{}}}. + +@item @@smallformat +Begin a kind of example. Like @code{@@format}, but use a smaller font +size where possible. Pair with @code{@@end smallformat}. +@xref{@code{@@small@dots{}}}. + +@item @@smallindentedblock +Like @code{@@indentedblock}, but use a smaller font size where +possible. Pair with @code{@@end smallindentedblock}. +@xref{@code{@@small@dots{}}}. + +@item @@smalllisp +Begin an example of Lisp code. Same as @code{@@smallexample}. Pair +with @code{@@end smalllisp}. @xref{@code{@@small@dots{}}}. + +@item @@smallquotation +Like @code{@@quotation}, but use a smaller font size where possible. +Pair with @code{@@end smallquotation}. @xref{@code{@@small@dots{}}}. + +@item @@sortas @{@var{key}@} +Used in the arguments to index commands to give a string by which the +index entry should be sorted. @xref{Indexing Commands}. + +@item @@sp @var{n} +Skip @var{n} blank lines. @xref{@code{@@sp}}. + +@item @@ss@{@} +Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. + +@item @@strong @{@var{text}@} +Emphasize @var{text} more strongly than @code{@@emph}, by using +@strong{boldface} where possible; enclosed in asterisks in Info. +@xref{emph & strong, , Emphasizing Text}. + +@item @@sub @{@var{text}@} +Set @var{text} as a subscript. @xref{Inserting Subscripts and Superscripts}. + +@item @@subheading @var{title} +Print an unnumbered subsection-like heading, but omit from the table +of contents of a printed manual. In Info, the title is underlined +with hyphens. @xref{@code{@@unnumberedsubsec @@appendixsubsec @@subheading}}. + +@item @@subsection @var{title} +Begin a subsection within a section. The subsection title appears in +the table of contents. In Info, the title is underlined with hyphens. +Same context-dependent numbering as @code{@@section}. +@xref{@code{@@subsection}}. + +@item @@subsubheading @var{title} +Print an unnumbered subsubsection-like heading, but omit from the +table of contents of a printed manual. In Info, the title is +underlined with periods. @xref{@code{@@subsubsection}}. + +@item @@subsubsection @var{title} +Begin a subsubsection within a subsection. The subsubsection title +appears in the table of contents. In Info, the title is underlined +with periods. Same context-dependent numbering as @code{@@section}. +@xref{@code{@@subsubsection}}. + +@item @@subtitle @var{title} +In a printed manual, set a subtitle in a normal sized font flush to +the right-hand side of the page. Not relevant to Info, which does not +have title pages. @xref{@code{@@title @@subtitle @@author}}. + +@item @@summarycontents +Print a short table of contents. Synonym for @code{@@shortcontents}. +@xref{Contents, , Generating a Table of Contents}. + +@item @@sup @{@var{text}@} +Set @var{text} as a superscript. @xref{Inserting Subscripts and Superscripts}. + +@item @@syncodeindex @var{from-index} @var{to-index} +Merge the index named in the first argument into the index named in +the second argument, formatting the entries from the first index with +@code{@@code}. @xref{Combining Indices}. + +@item @@synindex @var{from-index} @var{to-index} +Merge the index named in the first argument into the index named in +the second argument. Do not change the font of @var{from-index} +entries. @xref{Combining Indices}. + +@item @@t@{@var{text}@} +Set @var{text} in a @t{fixed-width}, typewriter-like font. No effect +in Info. @xref{Fonts}. + +@item @@tab +Separate columns in a row of a multitable. @xref{Multitable Rows}. + +@item @@table @var{formatting-command} +Begin a two-column table (description list), using @code{@@item} for +each entry. Write each first column entry on the same line as +@code{@@item}. First column entries are printed in the font resulting +from @var{formatting-command}. Pair with @code{@@end table}. +@xref{Two-column Tables, , Making a Two-column Table}. Also see +@ref{@code{@@ftable @@vtable}}, and @ref{@code{@@itemx}}. + +@item @@TeX@{@} +Generate the @TeX{} logo. @xref{@code{@@TeX @@LaTeX}}. + +@item @@tex +Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw +Formatter Commands}. + +@item @@textdegree@{@} +Generate the degree symbol. @xref{@code{@@textdegree}}. + +@item @@thischapter +@itemx @@thischaptername +@itemx @@thischapternum +@itemx @@thisfile +@itemx @@thispage +@itemx @@thistitle +Only allowed in a heading or footing. Stands for, respectively, the +number and name of the current chapter (in the format `Chapter 1: +Title'), the current chapter name only, the current chapter number +only, the filename, the current page number, and the title of the +document, respectively. @xref{Custom Headings, , How to Make Your Own +Headings}. + +@item @@TH@{@} +@itemx @@th@{@} +Generate the uppercase and lowercase Icelandic letter thorn, respectively: +@TH{}, @th{}. @xref{Inserting Accents}. + +@item @@tie@{@} +Generate a normal interword space at which a line break is not +allowed. @xref{@code{@@tie}}. + +@item @@tieaccent@{@var{cc}@} +Generate a tie-after accent over the next two characters @var{cc}, as in +`@tieaccent{oo}'. @xref{Inserting Accents}. + +@item @@tindex @var{entry} +Add @var{entry} to the index of data types. @xref{Index Entries, , +Defining the Entries of an Index}. + +@item @@title @var{title} +In a printed manual, set a title flush to the left-hand side of the +page in a larger than normal font and underline it with a black rule. +Not relevant to Info, which does not have title pages. +@xref{@code{@@title @@subtitle @@author}}. + +@item @@titlefont@{@var{text}@} +In a printed manual, print @var{text} in a larger than normal font. +@xref{@code{@@titlefont @@center @@sp}}. + +@item @@titlepage +Begin the title page. Write the command on a line of its own, paired +with @code{@@end titlepage}. Nothing between @code{@@titlepage} and +@code{@@end titlepage} appears in Info. @xref{@code{@@titlepage}}. + +@item @@today@{@} +Insert the current date, in `1 Jan 1900' style. @xref{Custom +Headings, , How to Make Your Own Headings}. + +@item @@top @var{title} +Mark the topmost @code{@@node} in the file, which must be defined on +the line immediately preceding the @code{@@top} command. The title is +formatted as a chapter-level heading. The entire top node, including +the @code{@@node} and @code{@@top} lines, are normally enclosed with +@code{@@ifnottex ... @@end ifnottex}. In @TeX{} and +@code{texinfo-format-buffer}, the @code{@@top} command is merely a +synonym for @code{@@unnumbered}. @xref{@command{makeinfo} Pointer +Creation}. + +@item @@U@{@var{hex}@} +Output a representation of Unicode character U+@var{hex}. +@xref{Inserting Unicode}. + +@item @@u@{@var{c}@} +@itemx @@ubaraccent@{@var{c}@} +@itemx @@udotaccent@{@var{c}@} +Generate a breve, underbar, or underdot accent, respectively, over or +under the character @var{c}, as in @u{o}, @ubaraccent{o}, +@udotaccent{o}. @xref{Inserting Accents}. + +@item @@unmacro @var{macroname} +Undefine the macro @code{@@@var{macroname}} if it has been defined. +@xref{Defining Macros}. + +@item @@unnumbered @var{title} +Begin a chapter that appears without chapter numbers of any kind. The +title appears in the table of contents. In Info, the title is +underlined with asterisks. @xref{@code{@@unnumbered @@appendix}}. + +@item @@unnumberedsec @var{title} +Begin a section that appears without section numbers of any kind. The +title appears in the table of contents of a printed manual. In Info, +the title is underlined with equal signs. @xref{@code{@@unnumberedsec +@@appendixsec @@heading}}. + +@item @@unnumberedsubsec @var{title} +Begin an unnumbered subsection. The title appears in the table of +contents. In Info, the title is underlined with hyphens. +@xref{@code{@@unnumberedsubsec @@appendixsubsec @@subheading}}. + +@item @@unnumberedsubsubsec @var{title} +Begin an unnumbered subsubsection. The title appears in the table of +contents. In Info, the title is underlined with periods. +@xref{@code{@@subsubsection}}. + +@item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@} +@itemx @@url@{@var{url}[, @var{displayed-text}][, @var{replacement}@} +Define a cross-reference to an external uniform resource locator, +e.g., for the World Wide Web. @xref{@code{@@url}}. + +@item @@urefbreakstyle @var{style} +Specify how @code{@@uref}/@code{@@url} should break at special +characters: @code{after}, @code{before}, @code{none}. +@xref{@code{@@url}}. + +@item @@v@{@var{c}@} +Generate check accent over the character @var{c}, as in @v{o}. +@xref{Inserting Accents}. + +@item @@validatemenus @var{on-off} +Control whether menus can be automatically generated. @xref{Writing a +Menu}. + +@item @@value@{@var{txivar}@} +Insert the value, if any, of the Texinfo variable @var{txivar}, +previously defined by @code{@@set}. @xref{@code{@@set @@clear +@@value}}. + +@item @@var@{@var{metasyntactic-variable}@} +Highlight a metasyntactic variable, which is something that stands for +another piece of text. @xref{@code{@@var}}. + +@item @@verb@{@var{delim} @var{literal} @var{delim}@} +Output @var{literal}, delimited by the single character @var{delim}, +exactly as is (in the fixed-width font), including any whitespace or +Texinfo special characters. @xref{@code{@@verb}}. + +@item @@verbatim +Output the text of the environment exactly as is (in the fixed-width +font). Pair with @code{@@end verbatim}. @xref{@code{@@verbatim}}. + +@item @@verbatiminclude @var{filename} +Output the contents of @var{filename} exactly as is (in the +fixed-width font). @xref{@code{@@verbatiminclude}}. + +@item @@vindex @var{entry} +Add @var{entry} to the index of variables. @xref{Index Entries, , +Defining the Entries of an Index}. + +@item @@vskip @var{amount} +In a printed manual, insert whitespace so as to push text on the +remainder of the page towards the bottom of the page. Used in +formatting the copyright page with the argument @samp{0pt plus +1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used +only in contexts ignored for Info. @xref{Copyright}. + +@item @@vtable @var{formatting-command} +Begin a two-column table, using @code{@@item} for each entry. +Automatically enter each of the items in the first column into the +index of variables. Pair with @code{@@end vtable}. The same as +@code{@@table}, except for indexing. @xref{@code{@@ftable @@vtable}}. + +@item @@w@{@var{text}@} +Disallow line breaks within @var{text}. @xref{@code{@@w}}. + +@item @@xml +Enter XML completely. Pair with @code{@@end xml}. @xref{Raw +Formatter Commands}. + +@item @@xref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} +Make a reference that starts with `See' in a printed manual. Follow +command with a punctuation mark. Only the first argument is +mandatory. @xref{@code{@@xref}}. + +@item @@xrefautomaticsectiontitle @var{on-off} +By default, use the section title instead of the node name in cross +references. @xref{Three Arguments}. + +@end table + + +@node Command Contexts +@section @@-Command Contexts + +@cindex Contexts, of @@-commands + +Here we describe approximately which @@-commands can be used in which +contexts. It not exhaustive or meant to be a complete reference. +Discrepancies between the information here and the @code{makeinfo} or +@TeX{} implementations are most likely to be resolved in favor of the +implementation. + +By @dfn{general text} below, we mean anything except sectioning and +other such outer-level document commands, such as @code{@@section}, +@code{@@node}, and @code{@@setfilename}. + +@code{@@c}, @code{@@comment} and @code{@@if ... @@end if} conditional +commands may appear anywhere (except the conditionals must still be on +lines by themselves). @code{@@caption} may only appear in +@code{@@float} but may contain general text. @code{@@footnote} +content likewise. + +@@-commands with braces marking text (such as @code{@@strong}, +@code{@@sc}, @code{@@asis}) may contain raw formatter commands such as +@code{@@html} but no other block commands (other commands terminated +by @code{@@end}) and may not be split across paragraphs, but may +otherwise contain general text. + +In addition to the block command restriction, on @code{@@center}, +@code{@@exdent} and @code{@@item} in @code{@@table} lines, @@-commands +that makes only sense in a paragraph are not accepted, such as +@code{@@indent}. + +In addition to the above, sectioning commands cannot contain +@code{@@anchor}, @code{@@footnote} or @code{@@verb}. + +In addition to the above, remaining commands (@code{@@node}, +@code{@@anchor}, @code{@@printindex}, @code{@@ref}, @code{@@math}, +@code{@@cindex}, @code{@@url}, @code{@@image}, and so on) cannot +contain cross-reference commands (@code{@@ref}, @code{@@xref}, +@code{@@pxref} and @code{@@inforef}). In one last addition, +@code{@@shortcaption} may only appear inside @code{@@float}. + +For precise and complete information, we suggest looking into the +test suite in the sources, which exhaustively tries combinations. + + +@node Obsolete @@-Commands +@section Obsolete @@-Commands + +Here are Texinfo @@-commands which are obsolete or have been removed +completely. This section is for historical purposes. + +@ftable @code +@item @@setcontentsaftertitlepage +@cindex Contents, after title page +@cindex Table of contents, after title page +In the past, the contents commands were sometimes placed at the end of +the file, after any indices and just before the @code{@@bye}, but we +no longer recommend this. +This command could be used by a user printing a manual, to force the +contents to be printed after the title page +(after the @samp{@@end titlepage} line) +even if the @code{@@contents} command was at the end of the manual. It +now does nothing. + +@item @@setshortcontentsaftertitlepage +This placed the short table of contents after the @samp{@@end titlepage} +command even if the @code{@@shortcontents} command was at the end. It +now does nothing. +@end ftable + + +@node Tips +@appendix Tips and Hints + +Here are some tips for writing Texinfo documentation: + +@cindex Tips +@cindex Usage tips +@cindex Hints +@itemize @bullet +@item +Write in the present tense, not in the past or the future. + +@item +Write actively! For example, write ``We recommend that @dots{}'' rather +than ``It is recommended that @dots{}''. + +@item +Use 70 or 72 as your fill column. Longer lines are hard to read. + +@item +Include a copyright notice and copying permissions. +@end itemize + + +@subsubheading Index, Index, Index! + +Write many index entries, in different ways. +Readers like indices; they are helpful and convenient. + +Although it is easiest to write index entries as you write the body of +the text, some people prefer to write entries afterwards. In either +case, write an entry before the paragraph to which it applies. This +way, an index entry points to the first page of a paragraph that is +split across pages. + +Here are more index-related hints we have found valuable: + +@itemize @bullet +@item +Write each index entry differently, so each entry refers to a different +place in the document. + +@item +Write index entries only where a topic is discussed significantly. For +example, it is not useful to index ``debugging information'' in a +chapter on reporting bugs. Someone who wants to know about debugging +information will certainly not find it in that chapter. + +@item +Consistently capitalize the first word of every concept index entry, +or else consistently use lowercase. Terse entries often call for +lowercase; longer entries for capitalization. Whichever case +convention you use, please use one or the other consistently! Mixing +the two styles looks bad. + +@item +Always capitalize or use uppercase for those words in an index for +which this is proper, such as names of countries or acronyms. Always +use the appropriate case for case-sensitive names, such as those in C or +Lisp. + +@item +Write the indexing commands that refer to a whole section immediately +after the section command, and write the indexing commands that refer to +a paragraph before that paragraph. + +In the example that follows, a blank line comes after the index +entry for ``Leaping'': + +@example +@group +@@section The Dog and the Fox +@@cindex Jumping, in general +@@cindex Leaping + +@@cindex Dog, lazy, jumped over +@@cindex Lazy dog jumped over +@@cindex Fox, jumps over dog +@@cindex Quick fox jumps over dog +The quick brown fox jumps over the lazy dog. +@end group +@end example + +@noindent +(Note that the example shows entries for the same concept that are +written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so +readers can look up the concept in different ways.) +@end itemize + + +@subsubheading Blank Lines + +@itemize @bullet +@item +Insert a blank line between a sectioning command and the first following +sentence or paragraph, or between the indexing commands associated with +the sectioning command and the first following sentence or paragraph, as +shown in the tip on indexing. It makes the source easier to read. + +@item +Always insert a blank line before a @code{@@table} command and after an +@code{@@end table} command; but never insert a blank line after an +@code{@@table} command. + +@need 1000 +For example, + +@example +@group +Types of fox: + +@@table @@samp +@@item Quick +Jump over lazy dogs. +@end group + +@group +@@item Brown +Also jump over lazy dogs. +@@end table + +@end group +@group +@@noindent +On the other hand, @dots{} +@end group +@end example + +Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end +itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the +same way. +@end itemize + + +@subsubheading Complete Phrases + +Complete phrases are easier to read than @dots{} + +@itemize @bullet +@item +Write entries in an itemized list as complete sentences; or at least, as +complete phrases. Incomplete expressions @dots{} awkward @dots{} like +this. + +@item +Write the prefatory sentence or phrase for a multi-item list or table as +a complete expression. Do not write ``You can set:''; instead, write +``You can set these variables:''. The former expression sounds cut off. +@end itemize + + +@subsubheading Editions, Dates and Versions + +Include edition numbers, version numbers, and dates in the +@code{@@copying} text (for people reading the Texinfo file, and for the +legal copyright in the output files). Then use @code{@@insertcopying} +in the @code{@@titlepage} section for people reading the printed +output (@pxref{Short Sample}). + +It is easiest to handle such version information using @code{@@set} +and @code{@@value}. @xref{@code{@@value} Example}, and @ref{GNU +Sample Texts}. + + +@subsubheading Definition Commands + +Definition commands are @code{@@deffn}, @code{@@defun}, +@code{@@defmac}, and the like, and enable you to write descriptions in +a uniform format. + +@itemize @bullet +@item +Write just one definition command for each entity you define with a +definition command. The automatic indexing feature creates an index +entry that leads the reader to the definition. + +@item +Use @code{@@table} @dots{} @code{@@end table} in an appendix that +contains a summary of functions, not @code{@@deffn} or other definition +commands. +@end itemize + + +@subsubheading Capitalization + +@itemize @bullet +@item +Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or +@samp{i} in uppercase. + +@item +Capitalize ``Info''; it is a name. + +@item +Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase +@samp{T} and @samp{X}. This command causes the formatters to +typeset the name according to the wishes of Donald Knuth, who wrote +@TeX{}. (Likewise @code{@@LaTeX@{@}} for @LaTeX{}.) +@end itemize + + +@subsubheading Spaces + +Do not use spaces to format a Texinfo file, except inside of +@code{@@example} @dots{} @code{@@end example} and other literal +environments and commands. + +@need 700 +For example, @TeX{} fills the following: + +@example +@group + @@kbd@{C-x v@} + @@kbd@{M-x vc-next-action@} + Perform the next logical operation + on the version-controlled file + corresponding to the current buffer. +@end group +@end example + +@need 950 +@noindent +so it looks like this: + +@iftex +@quotation + @kbd{C-x v} + @kbd{M-x vc-next-action} + Perform the next logical operation on the version-controlled file + corresponding to the current buffer. +@end quotation +@end iftex +@ifnottex +@quotation +`C-x v' `M-x vc-next-action' Perform the next logical operation on the +version-controlled file corresponding to the current buffer. +@end quotation +@end ifnottex + +@noindent +In this case, the text should be formatted with +@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table. + + +@subsubheading @@code, @@samp, @@var, and @samp{---} + +@itemize @bullet +@item +Use @code{@@code} around Lisp symbols, including command names. +For example, + +@example +The main function is @@code@{vc-next-action@}, @dots{} +@end example + +@item +Avoid putting letters such as @samp{s} immediately after an +@samp{@@code}. Such letters look bad. + +@item +Use @code{@@var} around meta-variables. Do not write angle brackets +around them. + +@item +Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{} +typesets these as a long dash and the Info formatters reduce three +hyphens to two. +@end itemize + + +@subsubheading Periods Outside of Quotes + +Place periods and other punctuation marks @emph{outside} of quotations, +unless the punctuation is part of the quotation. This practice goes +against some publishing conventions in the United States, but enables the +reader to distinguish between the contents of the quotation and the +whole passage. + +For example, you should write the following sentence with the period +outside the end quotation marks: + +@example +Evidently, @samp{au} is an abbreviation for ``author''. +@end example + +@noindent +since @samp{au} does @emph{not} serve as an abbreviation for +@samp{author.} (with a period following the word). + + +@subsubheading Introducing New Terms + +@itemize @bullet +@item +Introduce new terms so that a reader who does not know them can +understand them from context; or write a definition for the term. + +For example, in the following, the terms ``check in'', ``register'' and +``delta'' are all appearing for the first time; the example sentence should be +rewritten so they are understandable. + +@quotation +The major function assists you in checking in a file to your +version control system and registering successive sets of changes to +it as deltas. +@end quotation + +@item +Use the @code{@@dfn} command around a word being introduced, to indicate +that the reader should not expect to know the meaning already, and +should expect to learn the meaning from this passage. +@end itemize + + +@subsubheading Program Invocation Nodes + +You can invoke programs such as Emacs, GCC, and @code{gawk} from a +shell. The documentation for each program should contain a section that +describes this. Unfortunately, if the node names and titles for these +sections are all different, they are difficult for users to find. + +So, there is a convention to name such sections with a phrase beginning +with the word `Invoking', as in `Invoking Emacs'; this way, users can +find the section easily. + + +@subsubheading ANSI C Syntax + +When you use @code{@@example} to describe a C function's calling +conventions, use the ANSI C syntax, like this: + +@example +void dld_init (char *@@var@{path@}); +@end example + +@noindent +And in the subsequent discussion, refer to the argument values by +writing the same argument names, again highlighted with +@code{@@var}. + +@need 800 +Avoid the obsolete style that looks like this: + +@example +#include <dld.h> + +dld_init (path) + char *path; +@end example + +Also, it is best to avoid writing @code{#include} above the +declaration just to indicate that the function is declared in a +header file. The practice may give the misimpression that the +@code{#include} belongs near the declaration of the function. Either +state explicitly which header file holds the declaration or, better +yet, name the header file used for a group of functions at the +beginning of the section that describes the functions. + +@anchor{texi-elements-by-size} +@subsubheading Node Length + +Keep nodes (sections) to a reasonable length, whatever reasonable +might be in the given context. Don't hesitate to break up long nodes +into subnodes and have an extensive tree structure; that's what it's +there for. Many times, readers will probably try to find a single +specific point in the manual, using search, indexing, or just plain +guessing, rather than reading the whole thing from beginning to end. + +You can use the @command{texi-elements-by-size} utility to see a list +of all nodes (or sections) in the document, sorted by size (either +lines or words), to find candidates for splitting. It's in the +@file{util/} subdirectory of the Texinfo sources. + + +@subsubheading Bad Examples + +Here are several examples of bad writing to avoid: + +In this example, say, `` @dots{} you must @code{@@dfn}@{check +in@} the new version.'' That flows better. + +@quotation +When you are done editing the file, you must perform a +@code{@@dfn}@{check in@}. +@end quotation + +In the following example, say, ``@dots{} makes a unified interface such as VC +mode possible.'' + +@quotation +SCCS, RCS and other version-control systems all perform similar +functions in broadly similar ways (it is this resemblance which makes +a unified control mode like this possible). +@end quotation + +And in this example, you should specify what `it' refers to: + +@quotation +If you are working with other people, it assists in coordinating +everyone's changes so they do not step on each other. +@end quotation + + +@subsubheading And Finally @dots{} + +@itemize @bullet +@item +Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last +sound in the name `Bach'. But pronounce Texinfo as in `speck': +``teckinfo''. + +@item +Write notes for yourself at the very end of a Texinfo file after the +@code{@@bye}. None of the formatters process text after the +@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{} +@code{@@end ignore}. +@end itemize + + +@node Sample Texinfo Files +@appendix Sample Texinfo Files +@cindex Sample Texinfo files + +The first example from the first chapter (@pxref{Short Sample}) is +given here in its entirety, without commentary. The second example +includes the full texts to be used in GNU manuals. + +@menu +* Short Sample Texinfo File:: +* GNU Sample Texts:: +* Verbatim Copying License:: +* All-permissive Copying License:: +@end menu + + +@node Short Sample Texinfo File +@section Short Sample +@cindex Sample Texinfo file, no comments + +Here is a complete, short sample Texinfo file. You can see this file, +with comments, in the first chapter. @xref{Short Sample}. + +In a nutshell: The @command{makeinfo} program transforms a Texinfo +source file such as this into an Info file or HTML; and @TeX{} typesets +it for a printed manual. + + +@sp 1 +@example +\input texinfo +@@settitle Sample Manual 1.0 + +@@copying +This is a short example of a complete Texinfo file. + +Copyright @@copyright@{@} 2016 Free Software Foundation, Inc. +@@end copying + +@@titlepage +@@title Sample Title +@@page +@@vskip 0pt plus 1filll +@@insertcopying +@@end titlepage + +@@c Output the table of the contents at the beginning. +@@contents + +@@ifnottex +@@node Top +@@top GNU Sample + +This manual is for GNU Sample +(version @@value@{VERSION@}, @@value@{UPDATED@}). +@@end ifnottex + +@@menu +* First Chapter:: The first chapter is the + only chapter in this sample. +* Index:: Complete index. +@@end menu + + +@@node First Chapter +@@chapter First Chapter + +@@cindex chapter, first + +This is the first chapter. +@@cindex index entry, another + +Here is a numbered list. + +@@enumerate +@@item +This is the first item. + +@@item +This is the second item. +@@end enumerate + + +@@node Index +@@unnumbered Index + +@@printindex cp + +@@bye +@end example + + +@node GNU Sample Texts +@section GNU Sample Texts + +@cindex GNU sample texts +@cindex Sample texts, GNU +@cindex Full texts, GNU + +Following is a sample Texinfo document with the full texts that should +be used (adapted as necessary) in GNU manuals. + +As well as the legal texts, it also serves as a practical example of how +many elements in a GNU system can affect the manual. If you're not +familiar with all these different elements, don't worry. They're not +required and a perfectly good manual can be written without them. +They're included here nonetheless because many manuals do (or could) +benefit from them. + +@xref{Short Sample}, for a minimal example of a Texinfo file. +@xref{Beginning and Ending a File}, for a full explanation of that +minimal example. + +Here are some notes on the example: + +@itemize @bullet +@item +@cindex $Id +@cindex CVS $Id +@cindex RCS $Id +@cindex Documentation identification +@cindex Identification of documentation +The @samp{$Id:} comment is for the CVS +(@url{http://www.nongnu.org/cvs/}), RCS (@pxref{Top,,, rcs, Revision +Control System}) and other version control systems, which expand it +into a string such as: + +@example +$Id$ +@end example + +(This is potentially useful in all sources that use version control, +not just manuals.) You may wish to include the @samp{$Id:} comment in +the @code{@@copying} text, if you want a completely unambiguous +reference to the documentation source version. + +If you want to literally write @t{@w{$}Id$}, use @code{@@w}: +@code{@@w@{$@}Id$}. Unfortunately, this technique does not work in +plain text output, where it's not clear what should be done. + +@item +@pindex automake@r{, and version info} +@vindex UPDATED @r{Automake variable} +@vindex VERSION @r{Automake variable} +@pindex time-stamp.el +The @file{version.texi} in the @code{@@include} command is maintained +automatically by Automake (@pxref{Top,,, automake, GNU Automake}). It +sets the @samp{VERSION} and @samp{UPDATED} values used elsewhere. If +your distribution doesn't use Automake, but you do use Emacs, you may +find the time-stamp.el package helpful (@pxref{Time Stamps,,, emacs, +The GNU Emacs Manual}). + +@item +The @code{@@syncodeindex} command reflects the recommendation to use +only one index where possible, to make it easier for readers to look up +index entries. + +@item +The @code{@@dircategory} is for constructing the Info directory. +@xref{Installing Dir Entries}, which includes a variety of recommended +category names. + +@item +The `Invoking' node is a GNU standard to help users find the basic +information about command-line usage of a given program. @xref{Manual +Structure Details,,, standards, GNU Coding Standards}. + +@item +@cindex GNU Free Documentation License, including entire +@cindex Free Documentation License, including entire +It is best to include the entire GNU Free Documentation License in a GNU +manual, unless the manual is only a few pages long. Of course this +sample is even shorter than that, but it includes the FDL anyway in +order to show one conventional way to do so. The @file{fdl.texi} file +is available on the GNU machines and in the Texinfo and other GNU +source distributions. + +The FDL provides for omitting itself under certain conditions, but in +that case the sample texts given here have to be modified. @xref{GNU +Free Documentation License}. + +@item +If the FSF is not the copyright holder, then use the appropriate name. + +@item +If your manual is published on paper by the FSF or is longer than 400 +pages, you should include the standard FSF cover texts (@pxref{License +Notices for Documentation,,, maintain, GNU Maintainer Information}). + +@item +For documents that express your personal views, feelings or +experiences, it is more appropriate to use a license permitting only +verbatim copying, rather than the FDL@. @xref{Verbatim Copying +License}. + +@end itemize + +Here is the sample document: + +@verbatim +\input texinfo @c -*-texinfo-*- +@comment $Id@w{$} +@comment %**start of header +@include version.texi +@settitle GNU Sample @value{VERSION} +@syncodeindex pg cp +@comment %**end of header +@copying +This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}), +which is an example in the Texinfo documentation. + +Copyright @copyright{} 2016 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, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled +``GNU Free Documentation License''. +@end quotation +@end copying + +@dircategory Texinfo documentation system +@direntry +* sample: (sample)Invoking sample. +@end direntry + +@titlepage +@title GNU Sample +@subtitle for version @value{VERSION}, @value{UPDATED} +@author A.U. Thor (@email{bug-sample@@gnu.org}) +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top GNU Sample + +This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}). +@end ifnottex + +@menu +* Invoking sample:: +* GNU Free Documentation License:: +* Index:: +@end menu + + +@node Invoking sample +@chapter Invoking sample + +@pindex sample +@cindex invoking @command{sample} + +This is a sample manual. There is no sample program to +invoke, but if there were, you could see its basic usage +and command line options here. + + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@include fdl.texi + + +@node Index +@unnumbered Index + +@printindex cp + +@bye +@end verbatim + + +@node Verbatim Copying License +@section Verbatim Copying License + +@cindex Verbatim copying license +@cindex License for verbatim copying + +For software manuals and other documentation, it is critical to use a +license permitting free redistribution and updating, so that when a free +program is changed, the documentation can be updated as well. + +On the other hand, for documents that express your personal views, +feelings or experiences, it is more appropriate to use a license +permitting only verbatim copying. + +Here is sample text for such a license permitting verbatim copying only. +This is just the license text itself. For a complete sample document, +see the previous sections. + +@verbatim +@copying +This document is a sample for allowing verbatim copying only. + +Copyright @copyright{} 2016 Free Software Foundation, Inc. + +@quotation +Permission is granted to make and distribute verbatim copies +of this entire document without royalty provided the +copyright notice and this permission notice are preserved. +@end quotation +@end copying +@end verbatim + + +@node All-permissive Copying License +@section All-permissive Copying License + +@cindex All-permissive copying license +@cindex License for all-permissive copying + +For software manuals and other documentation, it is important to use a +license permitting free redistribution and updating, so that when a free +program is changed, the documentation can be updated as well. + +On the other hand, for small supporting files, short manuals (under 300 +lines long) and rough documentation (README files, INSTALL files, etc.), +the full FDL would be overkill. They can use a simple all-permissive +license. + +Here is sample text for such an all-permissive license. This is just +the license text itself. For a complete sample document, see the +previous sections. + +@example +Copyright @@copyright@{@} 2016 Free Software Foundation, Inc. + +Copying and distribution of this file, with or without modification, +are permitted in any medium without royalty provided the copyright +notice and this notice are preserved. +@end example + + +@node Texinfo Mode +@appendix Using Texinfo Mode +@cindex Texinfo mode +@cindex Mode, using Texinfo +@cindex GNU Emacs +@cindex Emacs + +You may edit a Texinfo file with any text editor you choose. A Texinfo +file is no different from any other ASCII file. However, GNU Emacs +comes with a special mode, called Texinfo mode, that provides Emacs +commands and tools to help ease your work. + +@menu +* Texinfo Mode Overview:: How Texinfo mode can help you. +* Emacs Editing:: Texinfo mode adds to GNU Emacs' general + purpose editing features. +* Inserting:: How to insert frequently used @@-commands. +* Showing the Structure:: How to show the structure of a file. +* Updating Nodes and Menus:: How to update or create new nodes and menus. +* Info Formatting:: How to format for Info. +* Printing:: How to format and print part or all of a file. +* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. +@end menu + +@node Texinfo Mode Overview +@section Texinfo Mode Overview + +Texinfo mode provides special features for working with Texinfo files. +You can: + +@itemize @bullet +@item +Insert frequently used @@-commands. + +@item +Automatically create @code{@@node} lines. + +@item +Show the structure of a Texinfo source file. + +@item +Automatically create or update the `Next', +`Previous', and `Up' pointers of a node. + +@item +Automatically create or update menus. + +@item +Automatically create a master menu. + +@item +Format a part or all of a file for Info. + +@item +Typeset and print part or all of a file. +@end itemize + +Perhaps the two most helpful features are those for inserting frequently +used @@-commands and for creating node pointers and menus. + +@node Emacs Editing +@section The Usual GNU Emacs Editing Commands + +In most cases, the usual Text mode commands work the same in Texinfo +mode as they do in Text mode. Texinfo mode adds new editing commands +and tools to GNU Emacs' general purpose editing features. The major +difference concerns filling. In Texinfo mode, the paragraph +separation variable and syntax table are redefined so that Texinfo +commands that should be on lines of their own are not inadvertently +included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph}) +command will refill a paragraph but not mix an indexing command on a +line adjacent to it into the paragraph. + +In addition, Texinfo mode sets the @code{page-delimiter} variable to +the value of @code{texinfo-chapter-level-regexp}; by default, this is +a regular expression matching the commands for chapters and their +equivalents, such as appendices. With this value for the page +delimiter, you can jump from chapter title to chapter title with the +@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} +(@code{backward-page}) commands and narrow to a chapter with the +@kbd{C-x n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs, +The GNU Emacs Manual}, for details about the page commands.) + +You may name a Texinfo file however you wish, but the convention is to +end a Texinfo file name with one of the extensions +@file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer +extension is preferred, since it is explicit, but a shorter extension +may be necessary for operating systems that limit the length of file +names. GNU Emacs automatically enters Texinfo mode when you visit a +file with a @file{.texinfo}, @file{.texi} or @file{.txi} +extension. Also, Emacs switches to Texinfo mode +when you visit a +file that has @samp{-*-texinfo-*-} in its first line. If ever you are +in another mode and wish to switch to Texinfo mode, type @code{M-x +texinfo-mode}. + +Like all other Emacs features, you can customize or enhance Texinfo +mode as you wish. In particular, the keybindings are very easy to +change. The keybindings described here are the default or standard +ones. + +@node Inserting +@section Inserting Frequently Used Commands +@cindex Inserting frequently used commands +@cindex Frequently used commands, inserting +@cindex Commands, inserting them + +Texinfo mode provides commands to insert various frequently used +@@-commands into the buffer. You can use these commands to save +keystrokes. + +The insert commands are invoked by typing @kbd{C-c} twice and then the +first letter of the @@-command: + +@table @kbd +@item C-c C-c c +@itemx M-x texinfo-insert-@@code +@findex texinfo-insert-@@code +Insert @code{@@code@{@}} and put the +cursor between the braces. + +@item C-c C-c d +@itemx M-x texinfo-insert-@@dfn +@findex texinfo-insert-@@dfn +Insert @code{@@dfn@{@}} and put the +cursor between the braces. + +@item C-c C-c e +@itemx M-x texinfo-insert-@@end +@findex texinfo-insert-@@end +Insert @code{@@end} and attempt to insert the correct following word, +such as @samp{example} or @samp{table}. (This command does not handle +nested lists correctly, but inserts the word appropriate to the +immediately preceding list.) + +@item C-c C-c i +@itemx M-x texinfo-insert-@@item +@findex texinfo-insert-@@item +Insert @code{@@item} and put the +cursor at the beginning of the next line. + +@item C-c C-c k +@itemx M-x texinfo-insert-@@kbd +@findex texinfo-insert-@@kbd +Insert @code{@@kbd@{@}} and put the +cursor between the braces. + +@item C-c C-c n +@itemx M-x texinfo-insert-@@node +@findex texinfo-insert-@@node +Insert @code{@@node} and a comment line +listing the sequence for the `Next', +`Previous', and `Up' nodes. +Leave point after the @code{@@node}. + +@item C-c C-c o +@itemx M-x texinfo-insert-@@noindent +@findex texinfo-insert-@@noindent +Insert @code{@@noindent} and put the +cursor at the beginning of the next line. + +@item C-c C-c r +@itemx M-x texinfo-insert-dwim-@@ref +@findex texinfo-insert-dwim-@@ref +This function and binding were added in Emacs 27.1. +Inserts one of @code{@@pxref@{@}}, @code{@@xref@{@}}, or +@code{@@ref@{@}} based on the text around point; calling it near an +unclosed preceding open parenthesis results in @code{@@pxref@{@}}, at +the beginning of a sentence or at @code{(point-min)} yields +@code{@@xref@{@}}, any other location (including inside a word), will +result in @code{@@ref@{@}}. A numeric argument says how many words +the braces should surround. Puts the cursor between the braces. + +@item C-c C-c s +@itemx M-x texinfo-insert-@@samp +@findex texinfo-insert-@@samp +Insert @code{@@samp@{@}} and put the +cursor between the braces. + +@item C-c C-c t +@itemx M-x texinfo-insert-@@table +@findex texinfo-insert-@@table +Insert @code{@@table} followed by a @key{SPC} +and leave the cursor after the @key{SPC}. + +@item C-c C-c v +@itemx M-x texinfo-insert-@@var +@findex texinfo-insert-@@var +Insert @code{@@var@{@}} and put the +cursor between the braces. + +@item C-c C-c x +@itemx M-x texinfo-insert-@@example +@findex texinfo-insert-@@example +Insert @code{@@example} and put the +cursor at the beginning of the next line. + +@c M-@{ was the binding for texinfo-insert-braces; +@c in Emacs 19, backward-paragraph will take this binding. +@item C-c C-c @{ +@itemx M-x texinfo-insert-braces +@findex texinfo-insert-braces +Insert @code{@{@}} and put the cursor between the braces. + +@item C-c @} +@itemx C-c ] +@itemx M-x up-list +@findex up-list +Move from between a pair of braces forward past the closing brace. +Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which +is, however, more mnemonic; hence the two keybindings. (Also, you can +move out from between braces by typing @kbd{C-f}.) +@end table + +To put a command such as @w{@code{@@code@{@dots{}@}}} around an +@emph{existing} word, position the cursor in front of the word and type +@kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text. +The value of the prefix argument tells Emacs how many words following +point to include between braces---@samp{1} for one word, @samp{2} for +two words, and so on. Use a negative argument to enclose the previous +word or words. If you do not specify a prefix argument, Emacs inserts +the @@-command string and positions the cursor between the braces. This +feature works only for those @@-commands that operate on a word or words +within one line, such as @code{@@kbd} and @code{@@var}. + +This set of insert commands was created after analyzing the frequency +with which different @@-commands are used in the @cite{GNU Emacs +Manual} and the @cite{GDB Manual}. If you wish to add your own insert +commands, you can bind a keyboard macro to a key, use abbreviations, +or extend the code in @file{texinfo.el}. + +@findex texinfo-start-menu-description +@cindex Menu description, start +@cindex Description for menu, start +@kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert +command that works differently from the other insert commands. It +inserts a node's section or chapter title in the space for the +description in a menu entry line. (A menu entry has three parts, the +entry name, the node name, and the description. Only the node name is +required, but a description helps explain what the node is about. +@xref{Menu Parts, , The Parts of a Menu}.) + +To use @code{texinfo-start-menu-description}, position point in a menu +entry line and type @kbd{C-c C-c C-d}. The command looks for and copies +the title that goes with the node name, and inserts the title as a +description; it positions point at beginning of the inserted text so you +can edit it. The function does not insert the title if the menu entry +line already contains a description. + +This command is only an aid to writing descriptions; it does not do the +whole job. You must edit the inserted text since a title tends to use +the same words as a node name but a useful description uses different +words. + +@node Showing the Structure +@section Showing the Sectioning Structure of a File +@cindex Showing the sectioning structure of a file +@cindex Sectioning structure of a file, showing +@cindex Structure of a file, showing +@cindex Outline of file structure, showing +@cindex Contents-like outline of file structure +@cindex File sectioning structure, showing +@cindex Texinfo file sectioning structure, showing + +You can show the sectioning structure of a Texinfo file by using the +@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command +lists the lines that begin with the @@-commands for @code{@@chapter}, +@code{@@section}, and the like. It constructs what amounts to a table +of contents. These lines are displayed in another buffer called the +@samp{*Occur*} buffer. In that buffer, you can position the cursor +over one of the lines and use the @kbd{C-c C-c} command +(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot +in the Texinfo file. + +@table @kbd +@item C-c C-s +@itemx M-x texinfo-show-structure +@findex texinfo-show-structure +Show the @code{@@chapter}, @code{@@section}, and such lines of a +Texinfo file. + +@item C-c C-c +@itemx M-x occur-mode-goto-occurrence +@findex occur-mode-goto-occurrence +Go to the line in the Texinfo file corresponding to the line under the +cursor in the @file{*Occur*} buffer. +@end table + +If you call @code{texinfo-show-structure} with a prefix argument by +typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the +@@-commands for @code{@@chapter}, @code{@@section}, and the like, but +also the @code{@@node} lines. You can use @code{texinfo-show-structure} +with a prefix argument to check whether the `Next', `Previous', and `Up' +pointers of an @code{@@node} line are correct. + +Often, when you are working on a manual, you will be interested only +in the structure of the current chapter. In this case, you can mark +off the region of the buffer that you are interested in by using the +@kbd{C-x n n} (@code{narrow-to-region}) command and +@code{texinfo-show-structure} will work on only that region. To see +the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}). +(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more +information about the narrowing commands.) + +@vindex page-delimiter +@cindex Page delimiter in Texinfo mode +In addition to providing the @code{texinfo-show-structure} command, +Texinfo mode sets the value of the page delimiter variable to match +the chapter-level @@-commands. This enables you to use the @kbd{C-x +]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) +commands to move forward and backward by chapter, and to use the +@kbd{C-x n p} (@code{narrow-to-page}) command to narrow to a chapter. +@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information +about the page commands. + + +@node Updating Nodes and Menus +@section Updating Nodes and Menus + +@cindex Updating nodes and menus +@cindex Create nodes, menus automatically +@cindex Insert nodes, menus automatically +@cindex Automatically insert nodes, menus + +Texinfo mode provides commands for automatically creating or updating +menus and node pointers. The commands are called ``update'' commands +because their most frequent use is for updating a Texinfo file after you +have worked on it; but you can use them to insert the `Next', +`Previous', and `Up' pointers into an @code{@@node} line that has none +and to create menus in a file that has none. + +If you do not use any updating commands, you need to write menus by +hand, which is a tedious task. + +@menu +* Updating Commands:: Five major updating commands. +* Updating Requirements:: How to structure a Texinfo file for + using the updating command. +* Other Updating Commands:: How to indent descriptions, insert + missing nodes lines, and update + nodes in sequence. +@end menu + +@node Updating Commands +@subsection The Updating Commands + +You can use the updating commands to: + +@itemize @bullet +@item +insert or update the `Next', `Previous', and `Up' pointers of a node, + +@item +insert or update the menu for a section, and + +@item +create a master menu for a Texinfo source file. +@end itemize + +You can also use the commands to update all the nodes and menus in a +region or in a whole Texinfo file. + +The updating commands work only with conventional Texinfo files, which +are structured hierarchically like books. In such files, a structuring +command line must follow closely after each @code{@@node} line, except +for the `Top' @code{@@node} line. (A @dfn{structuring command line} is +a line beginning with @code{@@chapter}, @code{@@section}, or other +similar command.) + +You can write the structuring command line on the line that follows +immediately after an @code{@@node} line or else on the line that +follows after a single @code{@@comment} line or a single +@code{@@ifinfo} line. You cannot interpose more than one line between +the @code{@@node} line and the structuring command line; and you may +interpose only a @code{@@comment} line or an @code{@@ifinfo} line. + +Commands which work on a whole buffer require that the `Top' node be +followed by a node with a @code{@@chapter} or equivalent-level command. +The menu updating commands will not create a main or master menu for a +Texinfo file that has only @code{@@chapter}-level nodes! The menu +updating commands only create menus @emph{within} nodes for lower level +nodes. To create a menu of chapters, you must provide a `Top' +node. + +The menu updating commands remove menu entries that refer to other Info +files since they do not refer to nodes within the current buffer. This +is a deficiency. Rather than use menu entries, you can use cross +references to refer to other Info files. None of the updating commands +affect cross-references. + +Texinfo mode has five updating commands that are used most often: two +are for updating the node pointers or menu of a single node (or a +region); two are for updating every node pointer and menu in a file; +and one, the @code{texinfo-master-menu} command, is for creating a +master menu for a complete file, and optionally, for updating every +node and menu in the whole Texinfo file. + +The @code{texinfo-master-menu} command is the primary command: + +@table @kbd +@item C-c C-u m +@itemx M-x texinfo-master-menu +@findex texinfo-master-menu +Create or update a master menu that includes all the other menus +(incorporating the descriptions from pre-existing menus, if +any). + +With an argument (prefix argument, @kbd{C-u,} if interactive), first create or +update all the nodes and all the regular menus in the buffer before +constructing the master menu. (@xref{The Top Node, , The Top Node and +Master Menu}, for more about a master menu.) + +For @code{texinfo-master-menu} to work, the Texinfo file must have a +`Top' node and at least one subsequent node. + +After extensively editing a Texinfo file, you can type the following: + +@example +C-u M-x texinfo-master-menu +@exdent or +C-u C-c C-u m +@end example + +@noindent +This updates all the nodes and menus completely and all at once. +@end table + +The other major updating commands do smaller jobs and are designed for +the person who updates nodes and menus as he or she writes a Texinfo +file. + +@need 1000 +The commands are: + +@table @kbd +@item C-c C-u C-n +@itemx M-x texinfo-update-node +@findex texinfo-update-node +Insert the `Next', `Previous', and `Up' pointers for the node that point is +within (i.e., for the @code{@@node} line preceding point). If the +@code{@@node} line has pre-existing `Next', `Previous', or `Up' +pointers in it, the old pointers are removed and new ones inserted. +With an argument (prefix argument, @kbd{C-u}, if interactive), this command +updates all @code{@@node} lines in the region (which is the text +between point and mark). + +@item C-c C-u C-m +@itemx M-x texinfo-make-menu +@findex texinfo-make-menu +Create or update the menu in the node that point is within. +With an argument (@kbd{C-u} as prefix argument, if +interactive), the command makes or updates menus for the +nodes which are either within or a part of the +region. + +Whenever @code{texinfo-make-menu} updates an existing menu, the +descriptions from that menu are incorporated into the new menu. This +is done by copying descriptions from the existing menu to the entries +in the new menu that have the same node names. If the node names are +different, the descriptions are not copied to the new menu. + +@item C-c C-u C-e +@itemx M-x texinfo-every-node-update +@findex texinfo-every-node-update +Insert or update the `Next', `Previous', and `Up' pointers for every +node in the buffer. + +@item C-c C-u C-a +@itemx M-x texinfo-all-menus-update +@findex texinfo-all-menus-update +Create or update all the menus in the buffer. With an argument +(@kbd{C-u} as prefix argument, if interactive), first insert +or update all the node +pointers before working on the menus. + +If a master menu exists, the @code{texinfo-all-menus-update} command +updates it; but the command does not create a new master menu if none +already exists. (Use the @code{texinfo-master-menu} command for +that.) + +When working on a document that does not merit a master menu, you can +type the following: + +@example +C-u C-c C-u C-a +@exdent or +C-u M-x texinfo-all-menus-update +@end example + +@noindent +This updates all the nodes and menus. +@end table + +The @code{texinfo-column-for-description} variable specifies the +column to which menu descriptions are indented. By default, the value +is 32 although it can be useful to reduce it to as low as 24. You +can set the variable via customization (@pxref{Customization,,, +emacs, The GNU Emacs Manual}) or with the @kbd{M-x set-variable} +command (@pxref{Examining, , Examining and Setting Variables, emacs, +The GNU Emacs Manual}). + +Also, the @code{texinfo-indent-menu-description} command may be used to +indent existing menu descriptions to a specified column. Finally, if +you wish, you can use the @code{texinfo-insert-node-lines} command to +insert missing @code{@@node} lines into a file. (@xref{Other Updating +Commands}, for more information.) + +@node Updating Requirements +@subsection Updating Requirements +@cindex Updating requirements +@cindex Requirements for updating commands + +To use the updating commands, you must organize the Texinfo file +hierarchically with chapters, sections, subsections, and the like. +When you construct the hierarchy of the manual, do not `jump down' +more than one level at a time: you can follow the `Top' node with a +chapter, but not with a section; you can follow a chapter with a +section, but not with a subsection. However, you may `jump up' any +number of levels at one time---for example, from a subsection to a +chapter. + +Each @code{@@node} line, with the exception of the line for the `Top' +node, must be followed by a line with a structuring command such as +@code{@@chapter}, @code{@@section}, or +@code{@@unnumberedsubsec}. + +Each @code{@@node} line/structuring-command line combination +must look either like this: + +@example +@group +@@node Comments, Minimum, Conventions, Overview +@@comment node-name, next, previous, up +@@section Comments +@end group +@end example + +or like this (without the @code{@@comment} line): + +@example +@group +@@node Comments, Minimum, Conventions, Overview +@@section Comments +@end group +@end example + +or like this (without the explicit node pointers): + +@example +@group +@@node Comments +@@section Comments +@end group +@end example + +@noindent +In this example, `Comments' is the name of both the node and the +section. The next node is called `Minimum' and the previous node is +called `Conventions'. The `Comments' section is within the `Overview' +node, which is specified by the `Up' pointer. (Instead of an +@code{@@comment} line, you may also write an @code{@@ifinfo} line.) + +If a file has a `Top' node, it must be called @samp{top} or @samp{Top} +and be the first node in the file. + +The menu updating commands create a menu of sections within a chapter, +a menu of subsections within a section, and so on. This means that +you must have a `Top' node if you want a menu of chapters. + +Incidentally, the @code{makeinfo} command will create an Info file for a +hierarchically organized Texinfo file that lacks `Next', `Previous' and +`Up' pointers. Thus, if you can be sure that your Texinfo file will be +formatted with @code{makeinfo}, you have no need for the update node +commands. (@xref{Creating an Info File}, for more information about +@code{makeinfo}.) + + +@node Other Updating Commands +@subsection Other Updating Commands + +In addition to the five major updating commands, Texinfo mode +possesses several less frequently used updating commands: + +@table @kbd +@item M-x texinfo-insert-node-lines +@findex texinfo-insert-node-lines +Insert @code{@@node} lines before the @code{@@chapter}, +@code{@@section}, and other sectioning commands wherever they are +missing throughout a region in a Texinfo file. + +With an argument (@kbd{C-u} as prefix argument, if interactive), the +command @code{texinfo-insert-node-lines} not only inserts +@code{@@node} lines but also inserts the chapter or section titles as +the names of the corresponding nodes. In addition, it inserts the +titles as node names in pre-existing @code{@@node} lines that lack +names. Since node names should be more concise than section or +chapter titles, you must manually edit node names so inserted. + +For example, the following marks a whole buffer as a region and inserts +@code{@@node} lines and titles throughout: + +@example +C-x h C-u M-x texinfo-insert-node-lines +@end example + +This command inserts titles as node names in @code{@@node} lines; the +@code{texinfo-start-menu-description} command (@pxref{Inserting, +Inserting Frequently Used Commands}) inserts titles as descriptions in +menu entries, a different action. However, in both cases, you need to +edit the inserted text. + +@item M-x texinfo-multiple-files-update +@findex texinfo-multiple-files-update @r{(in brief)} +Update nodes and menus in a document built from several separate files. +With @kbd{C-u} as a prefix argument, create and insert a master menu in +the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first +update all the menus and all the `Next', `Previous', and `Up' pointers +of all the included files before creating and inserting a master menu in +the outer file. The @code{texinfo-multiple-files-update} command is +described in the appendix on @code{@@include} files. +@xref{@code{texinfo-multiple-files-update}}. + +@item M-x texinfo-indent-menu-description +@findex texinfo-indent-menu-description +Indent every description in the menu following point to the specified +column. You can use this command to give yourself more space for +descriptions. With an argument (@kbd{C-u} as prefix argument, if +interactive), the @code{texinfo-indent-menu-description} command indents +every description in every menu in the region. However, this command +does not indent the second and subsequent lines of a multi-line +description. + +@item M-x texinfo-sequential-node-update +@findex texinfo-sequential-node-update +Insert the names of the nodes immediately following and preceding the +current node as the `Next' or `Previous' pointers regardless of those +nodes' hierarchical level. This means that the `Next' node of a +subsection may well be the next chapter. Sequentially ordered nodes are +useful for novels and other documents that you read through +sequentially. (However, in Info, the @kbd{g *} command lets +you look through the file sequentially, so sequentially ordered nodes +are not strictly necessary.) With an argument (prefix argument, if +interactive), the @code{texinfo-sequential-node-update} command +sequentially updates all the nodes in the region. +@end table + +@node Info Formatting +@section Formatting for Info +@cindex Formatting for Info +@cindex Running an Info formatter +@cindex Info formatting + +Texinfo mode provides several commands for formatting part or all of a +Texinfo file for Info. Often, when you are writing a document, you +want to format only part of a file---that is, a region. + +You can use either the @code{texinfo-format-region} or the +@code{makeinfo-region} command to format a region: + +@table @kbd +@findex texinfo-format-region +@item C-c C-e C-r +@itemx M-x texinfo-format-region +@itemx C-c C-m C-r +@itemx M-x makeinfo-region +Format the current region for Info. +@end table + +You can use either the @code{texinfo-format-buffer} or the +@code{makeinfo-buffer} command to format a whole buffer: + +@table @kbd +@findex texinfo-format-buffer +@item C-c C-e C-b +@itemx M-x texinfo-format-buffer +@itemx C-c C-m C-b +@itemx M-x makeinfo-buffer +Format the current buffer for Info. +@end table + +@need 1000 +For example, after writing a Texinfo file, you can type the following: + +@example +C-u C-c C-u m +@exdent or +C-u M-x texinfo-master-menu +@end example + +@noindent +This updates all the nodes and menus. Then type the following to create +an Info file: + +@example +C-c C-m C-b +@exdent or +M-x makeinfo-buffer +@end example + +@xref{Creating an Info File} for details about Info formatting. + +@node Printing +@comment node-name, next, previous, up +@section Printing +@cindex Formatting for printing +@cindex Printing a region or buffer +@cindex Region formatting and printing +@cindex Buffer formatting and printing +@cindex Part of file formatting and printing + +Typesetting and printing a Texinfo file is a multi-step process in +which you first create a file for printing (called a DVI file), and +then print the file. Optionally, you may also create indices. To do +this, you must run the @code{texindex} command after first running the +@code{tex} typesetting command; and then you must run the @code{tex} +command again. Or else run the @code{texi2dvi} command which +automatically creates indices as needed (@pxref{Format with +@command{texi2dvi}}). + +Often, when you are writing a document, you want to typeset and print +only part of a file to see what it will look like. You can use the +@code{texinfo-tex-region} and related commands for this purpose. Use +the @code{texinfo-tex-buffer} command to format all of a +buffer. + +@table @kbd +@item C-c C-t C-b +@itemx M-x texinfo-tex-buffer +@findex texinfo-tex-buffer +Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the +buffer, this command automatically creates or updates indices as +needed. + +@item C-c C-t C-r +@itemx M-x texinfo-tex-region +@findex texinfo-tex-region +Run @TeX{} on the region. + +@item C-c C-t C-i +@itemx M-x texinfo-texindex +Run @code{texindex} to sort the indices of a Texinfo file formatted with +@code{texinfo-tex-region}. The @code{texinfo-tex-region} command does +not run @code{texindex} automatically; it only runs the @code{tex} +typesetting command. You must run the @code{texinfo-tex-region} command +a second time after sorting the raw index files with the @code{texindex} +command. (Usually, you do not format an index when you format a region, +only when you format a buffer. Now that the @code{texi2dvi} command +exists, there is little or no need for this command.) + +@item C-c C-t C-p +@itemx M-x texinfo-tex-print +@findex texinfo-tex-print +Print the file (or the part of the file) previously formatted with +@code{texinfo-tex-buffer} or @code{texinfo-tex-region}. +@end table + +For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the +file @emph{must} start with a @samp{\input texinfo} line and must +include a @code{@@settitle} line. The file must end with @code{@@bye} +on a line by itself. (When you use @code{texinfo-tex-region}, you must +surround the @code{@@settitle} line with start-of-header and +end-of-header lines.) + +@xref{Hardcopy}, for a description of the other @TeX{} related +commands, such as @code{tex-show-print-queue}. + +@node Texinfo Mode Summary +@section Texinfo Mode Summary + +In Texinfo mode, each set of commands has default keybindings that +begin with the same keys. All the commands that are custom-created +for Texinfo mode begin with @kbd{C-c}. The keys are somewhat +mnemonic. + +@subheading Insert Commands + +The insert commands are invoked by typing @kbd{C-c} twice and then the +first letter of the @@-command to be inserted. (It might make more +sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but +@kbd{C-c C-c} is quick to type.) + +@example +C-c C-c c @r{Insert} @samp{@@code}. +C-c C-c d @r{Insert} @samp{@@dfn}. +C-c C-c e @r{Insert} @samp{@@end}. +C-c C-c i @r{Insert} @samp{@@item}. +C-c C-c n @r{Insert} @samp{@@node}. +C-c C-c s @r{Insert} @samp{@@samp}. +C-c C-c v @r{Insert} @samp{@@var}. +C-c @{ @r{Insert braces.} +C-c ] +C-c @} @r{Move out of enclosing braces.} + +@group +C-c C-c C-d @r{Insert a node's section title} + @r{in the space for the description} + @r{in a menu entry line.} +@end group +@end example + +@subheading Show Structure + +The @code{texinfo-show-structure} command is often used within a +narrowed region. + +@example +C-c C-s @r{List all the headings.} +@end example + +@subheading The Master Update Command + +The @code{texinfo-master-menu} command creates a master menu; and can +be used to update every node and menu in a file as well. + +@c Probably should use @tables in this section. +@example +@group +C-c C-u m +M-x texinfo-master-menu + @r{Create or update a master menu.} +@end group + +@group +C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first} + @r{create or update all nodes and regular} + @r{menus, and then create a master menu.} +@end group +@end example + +@subheading Update Pointers + +The update pointer commands are invoked by typing @kbd{C-c C-u} and +then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for +@code{texinfo-every-node-update}. + +@example +C-c C-u C-n @r{Update a node.} +C-c C-u C-e @r{Update every node in the buffer.} +@end example + +@subheading Update Menus + +Invoke the update menu commands by typing @kbd{C-c C-u} +and then either @kbd{C-m} for @code{texinfo-make-menu} or +@kbd{C-a} for @code{texinfo-all-menus-update}. To update +both nodes and menus at the same time, precede @kbd{C-c C-u +C-a} with @kbd{C-u}. + +@example +C-c C-u C-m @r{Make or update a menu.} + +@group +C-c C-u C-a @r{Make or update all} + @r{menus in a buffer.} +@end group + +@group +C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,} + @r{first create or update all nodes and} + @r{then create or update all menus.} +@end group +@end example + +@subheading Format for Info + +The Info formatting commands that are written in Emacs Lisp are +invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region +or @kbd{C-b} for the whole buffer. + +The Info formatting commands that are written in C and based on the +@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then +either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer. + +@need 800 +@noindent +Use the @code{texinfo-format@dots{}} commands: + +@example +@group +C-c C-e C-r @r{Format the region.} +C-c C-e C-b @r{Format the buffer.} +@end group +@end example + +@need 750 +@noindent +Use @code{makeinfo}: + +@example +C-c C-m C-r @r{Format the region.} +C-c C-m C-b @r{Format the buffer.} +C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.} +C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.} +@end example + +@subheading Typeset and Print + +The @TeX{} typesetting and printing commands are invoked by typing +@kbd{C-c C-t} and then another control command: @kbd{C-r} for +@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer}, +and so on. + +@example +C-c C-t C-r @r{Run @TeX{} on the region.} +C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.} +C-c C-t C-i @r{Run} @code{texindex}. +C-c C-t C-p @r{Print the DVI file.} +C-c C-t C-q @r{Show the print queue.} +C-c C-t C-d @r{Delete a job from the print queue.} +C-c C-t C-k @r{Kill the current @TeX{} formatting job.} +C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.} +C-c C-t C-l @r{Recenter the output buffer.} +@end example + +@subheading Other Updating Commands + +The remaining updating commands do not have standard keybindings because +they are rarely used. + +@example +@group +M-x texinfo-insert-node-lines + @r{Insert missing @code{@@node} lines in region.} + @r{With @kbd{C-u} as a prefix argument,} + @r{use section titles as node names.} +@end group + +@group +M-x texinfo-multiple-files-update + @r{Update a multi-file document.} + @r{With @kbd{C-u 2} as a prefix argument,} + @r{create or update all nodes and menus} + @r{in all included files first.} +@end group + +@group +M-x texinfo-indent-menu-description + @r{Indent descriptions.} +@end group + +@group +M-x texinfo-sequential-node-update + @r{Insert node pointers in strict sequence.} +@end group +@end example + + +@node Headings +@appendix Page Headings +@cindex Headings +@cindex Footings +@cindex Page numbering +@cindex Page headings +@cindex Formatting headings and footings + +Most printed manuals contain headings along the top of every page +except the title and copyright pages. Some manuals also contain +footings. @c HTML output also supports something like these, but in a +@c completely different way: @pxref{Customizing HTML Page Layout}. +Headings and footings have no meaning in Info or the other output +formats. + +@menu +* Headings Introduced:: Conventions for using page headings. +* Heading Format:: Standard page heading formats. +* Heading Choice:: How to specify the type of page heading. +* Custom Headings:: How to create your own headings and footings. +@end menu + +@node Headings Introduced +@section Headings Introduced + +Texinfo provides standard page heading formats for manuals that are +printed on one side of each sheet of paper and for manuals that are +printed on both sides of the paper. Typically, you will use these +formats, but you can specify your own format if you wish. + +In addition, you can specify whether chapters should begin on a new +page, or merely continue the same page as the previous chapter; and if +chapters begin on new pages, you can specify whether they must be +odd-numbered pages. + +By convention, a book is printed on both sides of each sheet of paper. +When you open a book, the right-hand page is odd-numbered, and +chapters begin on right-hand pages---a preceding left-hand page is +left blank if necessary. Reports, however, are often printed on just +one side of paper, and chapters begin on a fresh page immediately +following the end of the preceding chapter. In short or informal +reports, chapters often do not begin on a new page at all, but are +separated from the preceding text by a small amount of whitespace. + +The @code{@@setchapternewpage} command controls whether chapters begin +on new pages, and whether one of the standard heading formats is used. +In addition, Texinfo has several heading and footing commands that you +can use to generate your own heading and footing formats. + +In Texinfo, headings and footings are single lines at the tops and +bottoms of pages; you cannot create multiline headings or footings. +Each header or footer line is divided into three parts: a left part, a +middle part, and a right part. Any part, or a whole line, may be left +blank. Text for the left part of a header or footer line is set +flushleft; text for the middle part is centered; and, text for the +right part is set flushright. + + +@node Heading Format +@section Standard Heading Formats + +Texinfo provides two standard heading formats, one for manuals printed +on one side of each sheet of paper, and the other for manuals printed +on both sides of the paper. + +By default, nothing is specified for the footing of a Texinfo file, +so the footing remains blank. + +The standard format for single-sided printing consists of a header +line in which the left-hand part contains the name of the chapter, the +central part is blank, and the right-hand part contains the page +number. + +@need 950 +A single-sided page looks like this: + +@example +@group + _______________________ + | | + | chapter page number | + | | + | Start of text ... | + | ... | + | | +@end group +@end example + +The standard format for two-sided printing depends on whether the page +number is even or odd. By convention, even-numbered pages are on the +left- and odd-numbered pages are on the right. (@TeX{} will adjust the +widths of the left- and right-hand margins. Usually, widths are +correct, but during double-sided printing, it is wise to check that +pages will bind properly---sometimes a printer will produce output in +which the even-numbered pages have a larger right-hand margin than the +odd-numbered pages.) + +In the standard double-sided format, the left part of the left-hand +(even-numbered) page contains the page number, the central part is +blank, and the right part contains the title (specified by the +@code{@@settitle} command). The left part of the right-hand +(odd-numbered) page contains the name of the chapter, the central part +is blank, and the right part contains the page number. + +@need 750 +Two pages, side by side as in an open book, look like this: + +@example +@group + _______________________ _______________________ + | | | | + | page number title | | chapter page number | + | | | | + | Start of text ... | | More text ... | + | ... | | ... | + | | | | +@end group +@end example + +@noindent +The chapter name is preceded by the word ``Chapter'', the chapter number +and a colon. This makes it easier to keep track of where you are in the +manual. + +@node Heading Choice +@section Specifying the Type of Heading + +@TeX{} does not begin to generate page headings for a standard Texinfo +file until it reaches the @code{@@end titlepage} command. Thus, the +title and copyright pages are not numbered. The @code{@@end +titlepage} command causes @TeX{} to begin to generate page headings +according to a standard format specified by the +@code{@@setchapternewpage} command that precedes the +@code{@@titlepage} section. + +@need 1000 +There are four possibilities: + +@table @asis +@item No @code{@@setchapternewpage} command +Cause @TeX{} to specify the single-sided heading format, with chapters +on new pages. This is the same as @code{@@setchapternewpage on}. + +@item @code{@@setchapternewpage on} +Specify the single-sided heading format, with chapters on new pages. + +@item @code{@@setchapternewpage off} +Cause @TeX{} to start a new chapter on the same page as the last page +of the preceding chapter, after skipping some vertical whitespace. +Also cause @TeX{} to typeset for single-sided printing. (You can +override the headers format with the @code{@@headings double} command; +@pxref{@code{@@headings}}.) + +@item @code{@@setchapternewpage odd} +Specify the double-sided heading format, with chapters on new pages. +@end table + +@noindent +Texinfo lacks a @code{@@setchapternewpage even} command. + + +@node Custom Headings +@section How to Make Your Own Headings + +You can use the standard headings provided with Texinfo or specify +your own. By default, Texinfo has no footers, so if you specify them, +the available page size for the main text will be slightly reduced. + +Texinfo provides six commands for specifying headings and +footings: +@itemize @bullet +@item +@code{@@everyheading} and @code{@@everyfooting} generate page headers and +footers that are the same for both even- and odd-numbered pages. +@item +@code{@@evenheading} and @code{@@evenfooting} command generate headers +and footers for even-numbered (left-hand) pages. +@item +@code{@@oddheading} and @code{@@oddfooting} generate headers and footers +for odd-numbered (right-hand) pages. +@end itemize + +Write custom heading specifications in the Texinfo file immediately +after the @code{@@end titlepage} command. You must cancel the +predefined heading commands with the @code{@@headings off} command +before defining your own specifications. + +@need 1000 +Here is how to tell @TeX{} to place the chapter name at the left, the +page number in the center, and the date at the right of every header +for both even- and odd-numbered pages: + +@example +@group +@@headings off +@@everyheading @@thischapter @@| @@thispage @@| @@today@{@} +@end group +@end example + +@noindent +You need to divide the left part from the central part and the central +part from the right part by inserting @samp{@@|} between parts. +Otherwise, the specification command will not be able to tell where +the text for one part ends and the next part begins. + +Each part can contain text or @@-commands. The text is printed as if +the part were within an ordinary paragraph in the body of the page. +The @@-commands replace themselves with the page number, date, chapter +name, or whatever. + +@need 950 +Here are the six heading and footing commands: + +@table @code +@item @@everyheading @var{left} @@| @var{center} @@| @var{right} +@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right} +@findex everyheading +@findex everyfooting +The `every' commands specify the format for both even- and odd-numbered +pages. These commands are for documents that are printed on one side +of each sheet of paper, or for documents in which you want symmetrical +headers or footers. + +@item @@evenheading @var{left} @@| @var{center} @@| @var{right} +@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right} +@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right} +@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right} +@findex evenheading +@findex evenfooting +@findex oddheading +@findex oddfooting +The `even' and `odd' commands specify the format for even-numbered +pages and odd-numbered pages. These commands are for books and +manuals that are printed on both sides of each sheet of paper. +@end table + +Use the @samp{@@this@dots{}} series of @@-commands to +provide the names of chapters +and sections and the page number. You can use the +@samp{@@this@dots{}} commands in the left, center, or right portions +of headers and footers, or anywhere else in a Texinfo file so long as +they are between @code{@@iftex} and @code{@@end iftex} commands. + +@need 1000 +Here are the @samp{@@this@dots{}} commands: + +@table @code +@item @@thispage +@findex thispage +Expands to the current page number. + +@item @@thissectionname +@findex thissectionname +Expands to the name of the current section. + +@item @@thissectionnum +@findex thissectionnum +Expands to the number of the current section. + +@item @@thissection +@findex thissection +Expands to the number and name of the current section, in the format +`Section 1: Title'. + +@item @@thischaptername +@findex thischaptername +Expands to the name of the current chapter. + +@item @@thischapternum +@findex thischapternum +Expands to the number of the current chapter, or letter of the current +appendix. + +@item @@thischapter +@findex thischapter +Expands to the number and name of the current +chapter, in the format `Chapter 1: Title'. + +@item @@thistitle +@findex thistitle +Expands to the name of the document, as specified by the +@code{@@settitle} command. + +@item @@thisfile +@findex thisfile +For @code{@@include} files only: expands to the name of the current +@code{@@include} file. If the current Texinfo source file is not an +@code{@@include} file, this command has no effect. This command does +@emph{not} provide the name of the current Texinfo source file unless +it is an @code{@@include} file. (@xref{Include Files}, for more +information about @code{@@include} files.) +@end table + +@noindent +You can also use the @code{@@today@{@}} command, which expands to the +current date, in `1 Jan 1900' format. +@findex today + +Other @@-commands and text are printed in a header or footer just as +if they were in the body of a page. It is useful to incorporate text, +particularly when you are writing drafts: + +@example +@group +@@headings off +@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter +@@everyfooting @@| @@| Version: 0.27: @@today@{@} +@end group +@end example + +Beware of overlong titles: they may overlap another part of the +header or footer and blot it out. + +If you have very short chapters and/or sections, several of them can +appear on a single page. You can specify which chapters and sections +you want @code{@@thischapter}, @code{@@thissection} and other such +macros to refer to on such pages as follows: + +@table @code +@item @@everyheadingmarks @var{ref} +@itemx @@everyfootingmarks @var{ref} +@findex everyheadingmarks +@findex everyfootingmarks +The @var{ref} argument can be either @code{top} (the @code{@@this...} +commands will refer to the chapter/section at the top of a page) or +@code{bottom} (the commands will reflect the situation at the bottom +of a page). These @samp{@@every...} commands specify what to do on +both even- and odd-numbered pages. + +@item @@evenheadingmarks @var{ref} +@itemx @@oddheadingmarks @var{ref} +@itemx @@evenfootingmarks @var{ref} +@itemx @@oddfootingmarks @var{ref} +@findex evenheadingmarks +@findex oddheadingmarks +@findex evenfootingmarks +@findex oddfootingmarks +These @samp{@@even...} and @samp{@@odd...} commands specify what to do +on only even- or odd-numbered pages, respectively. The @var{ref} +argument is the same as with the @samp{@@every...} commands. +@end table + +Write these commands immediately after the @code{@@...contents} +commands, or after the @code{@@end titlepage} command if you don't +have a table of contents or if it is printed at the end of your +manual. + +By default the @code{@@this...} commands reflect the situation at the +bottom of a page both in headings and in footings. + + +@node Catching Mistakes +@appendix Catching Mistakes +@cindex Structure, catching mistakes in +@cindex Nodes, catching mistakes +@cindex Catching mistakes +@cindex Correcting mistakes +@cindex Mistakes, catching +@cindex Problems, catching +@cindex Debugging the Texinfo structure + +Besides mistakes in the content of your documentation, there are two +kinds of mistake you can make with Texinfo: you can make mistakes with +@@-commands, and you can make mistakes with the structure of the nodes +and chapters. + +Emacs has two tools for catching the @@-command mistakes and two for +catching structuring mistakes. + +For finding problems with @@-commands, you can run @TeX{} or a region +formatting command on the region that has a problem; indeed, you can +run these commands on each region as you write it. + +For finding problems with the structure of nodes and chapters, you can use +@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur} +command and you can use the @kbd{M-x Info-validate} command. + +@menu +* @command{makeinfo} Preferred:: @code{makeinfo} finds errors. +* Debugging with Info:: How to catch errors with Info formatting. +* Debugging with @TeX{}:: How to catch errors with @TeX{} formatting. +* Using @code{texinfo-show-structure}:: How to use @code{texinfo-show-structure}. +* Using @code{occur}:: How to list all lines containing a pattern. +* Running @code{Info-validate}:: How to find badly referenced nodes. +@end menu + + +@node @command{makeinfo} Preferred +@section @command{makeinfo} Preferred + +@c anchor{makeinfo Preferred}@c prev name + +The @code{makeinfo} program does an excellent job of catching errors +and reporting them---far better than @code{texinfo-format-region} or +@code{texinfo-format-buffer}. In addition, the various functions for +automatically creating and updating node pointers and menus remove +many opportunities for human error. + +If you can, use the updating commands to create and insert pointers +and menus. These prevent many errors. Then use @code{makeinfo} (or +its Texinfo mode manifestations, @code{makeinfo-region} and +@code{makeinfo-buffer}) to format your file and check for other +errors. This is the best way to work with Texinfo. But if you +cannot use @code{makeinfo}, or your problem is very puzzling, then you +may want to use the tools described in this appendix. + + +@node Debugging with Info +@section Catching Errors with Info Formatting +@cindex Catching errors with Info formatting +@cindex Debugging with Info formatting + +After you have written part of a Texinfo file, you can use the +@code{texinfo-format-region} or the @code{makeinfo-region} command to +see whether the region formats properly. + +Most likely, however, you are reading this section because for some +reason you cannot use the @code{makeinfo-region} command; therefore, the +rest of this section presumes that you are using +@code{texinfo-format-region}. + +If you have made a mistake with an @@-command, +@code{texinfo-format-region} will stop processing at or after the +error and display an error message. To see where in the buffer the +error occurred, switch to the @samp{*Info Region*} buffer; the cursor +will be in a position that is after the location of the error. Also, +the text will not be formatted after the place where the error +occurred (or more precisely, where it was detected). + +For example, if you accidentally end a menu with the command @code{@@end +menus} with an `s' on the end, instead of with @code{@@end menu}, you +will see an error message that says: + +@example +@@end menus is not handled by texinfo +@end example + +@noindent +The cursor will stop at the point in the buffer where the error +occurs, or not long after it. The buffer will look like this: + +@example +@group +---------- Buffer: *Info Region* ---------- +* Menu: + +* Using texinfo-show-structure:: How to use + `texinfo-show-structure' + to catch mistakes. +* Running Info-validate:: How to check for + unreferenced nodes. +@@end menus +@point{} +---------- Buffer: *Info Region* ---------- +@end group +@end example + +The @code{texinfo-format-region} command sometimes provides slightly +odd error messages. For example, the following cross-reference fails +to format: + +@example +(@@xref@{Catching Mistakes, for more info.) +@end example + +@noindent +In this case, @code{texinfo-format-region} detects the missing closing +brace but displays a message that says @samp{Unbalanced parentheses} +rather than @samp{Unbalanced braces}. This is because the formatting +command looks for mismatches between braces as if they were +parentheses. + +Sometimes @code{texinfo-format-region} fails to detect mistakes. For +example, in the following, the closing brace is swapped with the +closing parenthesis: + +@example +(@@xref@{Catching Mistakes), for more info.@} +@end example + +@noindent +Formatting produces: +@example +(*Note for more info.: Catching Mistakes) +@end example + +The only way for you to detect this error is to realize that the +reference should have looked like this: + +@example +(*Note Catching Mistakes::, for more info.) +@end example + +Incidentally, if you are reading this node in Info and type @kbd{f +@key{RET}} (@code{Info-follow-reference}), you will generate an error +message that says: + +@example +No such node: "Catching Mistakes) The only way @dots{} +@end example + +@noindent +This is because Info perceives the example of the error as the first +cross-reference in this node and if you type a @key{RET} immediately +after typing the Info @kbd{f} command, Info will attempt to go to the +referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info +will complete the node name of the correctly written example and take +you to the `Catching Mistakes' node. (If you try this, you can return +from the `Catching Mistakes' node by typing @kbd{l} +(@code{Info-last}).) + + +@node Debugging with @TeX{} +@section Debugging with @TeX{} +@cindex Catching errors with @TeX{} formatting +@cindex Debugging with @TeX{} formatting + +You can also catch mistakes when you format a file with @TeX{}. + +Usually, you will want to do this after you have run +@code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on +the same file, because @code{texinfo-format-buffer} sometimes displays +error messages that make more sense than @TeX{}. (@xref{Debugging +with Info}, for more information.) + +For example, @TeX{} was run on a Texinfo file, part of which is shown +here: + +@example +---------- Buffer: texinfo.texi ---------- +name of the Texinfo file as an extension. The +@@samp@{??@} are `wildcards' that cause the shell to +substitute all the raw index files. (@@xref@{sorting +indices, for more information about sorting +indices.)@@refill +---------- Buffer: texinfo.texi ---------- +@end example + +@noindent +(The cross-reference lacks a closing brace.) +@TeX{} produced the following output, after which it stopped: + +@example +---------- Buffer: *tex-shell* ---------- +Runaway argument? +@{sorting indices, for more information about sorting +indices.) @@refill @@ETC. +! Paragraph ended before @@xref was complete. +<to be read again> + @@par +l.27 + +? +---------- Buffer: *tex-shell* ---------- +@end example + +In this case, @TeX{} produced an accurate and +understandable error message: + +@example +Paragraph ended before @@xref was complete. +@end example + +@noindent +@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo. +@samp{l.27} means that @TeX{} detected the problem on line 27 of the +Texinfo file. The @samp{?} is the prompt @TeX{} uses in this +circumstance. + +Unfortunately, @TeX{} is not always so helpful, and sometimes you must +truly be a Sherlock Holmes to discover what went wrong. + +In any case, if you run into a problem like this, you can do one of three +things. + +@enumerate +@item +You can tell @TeX{} to continue running and ignore just this error by +typing @key{RET} at the @samp{?} prompt. + +@item +You can tell @TeX{} to continue running and to ignore all errors as best +it can by typing @kbd{r @key{RET}} at the @samp{?} prompt. + +This is often the best thing to do. However, beware: the one error +may produce a cascade of additional error messages as its consequences +are felt through the rest of the file. To stop @TeX{} when it is +producing such an avalanche of error messages, type @kbd{C-c} (or +@kbd{C-c C-c}, if you are running a shell inside Emacs). + +@item +You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} +at the @samp{?} prompt. +@end enumerate + +If you are running @TeX{} inside Emacs, you need to switch to the shell +buffer and line at which @TeX{} offers the @samp{?} prompt. + +Sometimes @TeX{} will format a file without producing error messages even +though there is a problem. This usually occurs if a command is not ended +but @TeX{} is able to continue processing anyhow. For example, if you fail +to end an itemized list with the @code{@@end itemize} command, @TeX{} will +write a DVI file that you can print out. The only error message that +@TeX{} will give you is the somewhat mysterious comment: + +@example +(@@end occurred inside a group at level 1) +@end example + +@noindent +However, if you print the DVI file, you will find that the text +of the file that follows the itemized list is entirely indented as if +it were part of the last item in the itemized list. The error message +is the way @TeX{} says that it expected to find an @code{@@end} +command somewhere in the file; but that it could not determine where +it was needed. + +Another source of notoriously hard-to-find errors is a missing +@code{@@end group} command. If you ever are stumped by +incomprehensible errors, look for a missing @code{@@end group} command +first. + +If the Texinfo file lacks header lines, +@TeX{} may stop in the +beginning of its run and display output that looks like the following. +The @samp{*} indicates that @TeX{} is waiting for input. + +@example +This is TeX, Version 3.14159 (Web2c 7.0) +(test.texinfo [1]) +* +@end example + +@noindent +In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then +write the header lines in the Texinfo file and run the @TeX{} command +again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\} +instead of @samp{@@}; and in this circumstance, you are working +directly with @TeX{}, not with Texinfo.) + +@node Using @code{texinfo-show-structure} +@section Using @code{texinfo-show-structure} + +@cindex Showing the structure of a file +@findex texinfo-show-structure + +It is not always easy to keep track of the nodes, chapters, sections, and +subsections of a Texinfo file. This is especially true if you are revising +or adding to a Texinfo file that someone else has written. + +In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure} +command lists all the lines that begin with the @@-commands that +specify the structure: @code{@@chapter}, @code{@@section}, +@code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}} +as prefix argument, if interactive), +the command also shows the @code{@@node} lines. The +@code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in +Texinfo mode, by default. + +The lines are displayed in a buffer called the @samp{*Occur*} buffer, +indented by hierarchical level. For example, here is a part of what was +produced by running @code{texinfo-show-structure} on this manual: + +@example +@group +Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\| +unnum\\|major\\|chapheading \\|heading \\|appendix\\)" +in buffer texinfo.texi. +@dots{} +4177:@@chapter Nodes +4198: @@heading Two Paths +4231: @@section Node and Menu Illustration +4337: @@section The @@code@{@@@@node@} Command +4393: @@subheading Choosing Node and Pointer Names +4417: @@subsection How to Write a @@code@{@@@@node@} Line +4469: @@subsection @@code@{@@@@node@} Line Tips +@dots{} +@end group +@end example + +This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin +with the @code{@@section}, @code{@@subheading}, and @code{@@subsection} +commands respectively. If you move your cursor into the @samp{*Occur*} +window, you can position the cursor over one of the lines and use the +@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to +the corresponding spot in the Texinfo file. @xref{Other Repeating +Search, , Using Occur, emacs, The GNU Emacs Manual}, for more +information about @code{occur-mode-goto-occurrence}. + +The first line in the @samp{*Occur*} window describes the @dfn{regular +expression} specified by @var{texinfo-heading-pattern}. This regular +expression is the pattern that @code{texinfo-show-structure} looks for. +@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual}, +for more information. + +When you invoke the @code{texinfo-show-structure} command, Emacs will +display the structure of the whole buffer. If you want to see the +structure of just a part of the buffer, of one chapter, for example, +use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the +region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is +how the example used above was generated. (To see the whole buffer +again, use @kbd{C-x n w} (@code{widen}).) + +If you call @code{texinfo-show-structure} with a prefix argument by +typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with +@code{@@node} as well as the lines beginning with the @@-sign commands +for @code{@@chapter}, @code{@@section}, and the like. + +You can remind yourself of the structure of a Texinfo file by looking at +the list in the @samp{*Occur*} window; and if you have mis-named a node +or left out a section, you can correct the mistake. + +@node Using @code{occur} +@section Using @code{occur} + +@cindex Occurrences, listing with @code{@@occur} +@findex occur + +Sometimes the @code{texinfo-show-structure} command produces too much +information. Perhaps you want to remind yourself of the overall structure +of a Texinfo file, and are overwhelmed by the detailed list produced by +@code{texinfo-show-structure}. In this case, you can use the @code{occur} +command directly. To do this, type: + +@example +@kbd{M-x occur} +@end example + +@noindent +and then, when prompted, type a @dfn{regexp}, a regular expression for +the pattern you want to match. (@xref{Regexps, , Regular Expressions, +emacs, The GNU Emacs Manual}.) The @code{occur} command works from +the current location of the cursor in the buffer to the end of the +buffer. If you want to run @code{occur} on the whole buffer, place +the cursor at the beginning of the buffer. + +For example, to see all the lines that contain the word +@samp{@@chapter} in them, just type @samp{@@chapter}. This will +produce a list of the chapters. It will also list all the sentences +with @samp{@@chapter} in the middle of the line. + +If you want to see only those lines that start with the word +@samp{@@chapter}, type @samp{^@@chapter} when prompted by +@code{occur}. If you want to see all the lines that end with a word +or phrase, end the last word with a @samp{$}; for example, +@samp{catching mistakes$}. This can be helpful when you want to see +all the nodes that are part of the same chapter or section and +therefore have the same `Up' pointer. + +@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual}, +for more information. + + +@node Running @code{Info-validate} +@section Finding Badly Referenced Nodes + +@anchor{Running Info-Validate}@c old name +@findex Info-validate +@cindex Nodes, checking for badly referenced +@cindex Checking for badly referenced nodes +@cindex Looking for badly referenced nodes +@cindex Finding badly referenced nodes +@cindex Badly referenced nodes + +You can use the @code{Info-validate} command to check whether any of +the `Next', `Previous', `Up' or other node pointers fail to point to a +node. This command checks that every node pointer points to an +existing node. The @code{Info-validate} command works only on Info +files, not on Texinfo files. + +The @code{makeinfo} program validates pointers automatically, so you +do not need to use the @code{Info-validate} command if you are using +@code{makeinfo}. You only may need to use @code{Info-validate} if you +are unable to run @code{makeinfo} and instead must create an Info file +using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or +if you write an Info file from scratch. + +@menu +* Using @code{Info-validate}:: How to run @code{Info-validate}. +* Unsplit:: How to create an unsplit file. +* Tagifying:: How to tagify a file. +* Splitting:: How to split a file manually. +@end menu + + +@node Using @code{Info-validate} +@subsection Using @code{Info-validate} + +@cindex Using @code{Info-validate} +@cindex Info validating a large file +@cindex Validating a large file + +To use @code{Info-validate}, visit the Info file you wish to check and +type: + +@example +M-x Info-validate +@end example + +@noindent +Note that the @code{Info-validate} command requires an uppercase +`I'@. You may also need to create a tag table before running +@code{Info-validate}. @xref{Tagifying}. + +If your file is valid, you will receive a message that says ``File appears +valid''. However, if you have a pointer that does not point to a node, +error messages will be displayed in a buffer called @samp{*problems in +info file*}. + +For example, @code{Info-validate} was run on a test file that contained +only the first node of this manual. One of the messages said: + +@example +In node "Overview", invalid Next: Texinfo Mode +@end example + +@noindent +This meant that the node called @samp{Overview} had a `Next' pointer that +did not point to anything (which was true in this case, since the test file +had only one node in it). + +Now suppose we add a node named @samp{Texinfo Mode} to our test case +but we do not specify a `Previous' for this node. Then we will get +the following error message: + +@example +In node "Texinfo Mode", should have Previous: Overview +@end example + +@noindent +This is because every `Next' pointer should be matched by a +`Previous' (in the node where the `Next' points) which points back. + +@code{Info-validate} also checks that all menu entries and cross-references +point to actual nodes. + +@code{Info-validate} requires a tag table and does not work with files +that have been split. (The @code{texinfo-format-buffer} command +automatically splits large files.) In order to use @code{Info-validate} +on a large file, you must run @code{texinfo-format-buffer} with an +argument so that it does not split the Info file; and you must create a +tag table for the unsplit file. + +@node Unsplit +@subsection Creating an Unsplit File +@cindex Creating an unsplit file +@cindex Unsplit file creation + +You can run @code{Info-validate} only on a single Info file that has a +tag table. The command will not work on the indirect subfiles that +are generated when a master file is split. If you have a large file +(longer than 300,000 bytes or so), you need to run the +@code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such +a way that it does not create indirect subfiles. You will also need +to create a tag table for the Info file. After you have done this, +you can run @code{Info-validate} and look for badly referenced +nodes. + +The first step is to create an unsplit Info file. To prevent +@code{texinfo-format-buffer} from splitting a Texinfo file into +smaller Info files, give a prefix to the @kbd{M-x +texinfo-format-buffer} command: + +@example +C-u M-x texinfo-format-buffer +@end example + +@noindent +or else + +@example +C-u C-c C-e C-b +@end example + +@noindent +When you do this, Texinfo will not split the file and will not create +a tag table for it. +@cindex Making a tag table manually +@cindex Tag table, making manually + +@node Tagifying +@subsection Tagifying a File + +After creating an unsplit Info file, you must create a tag table for +it. Visit the Info file you wish to tagify and type: + +@example +M-x Info-tagify +@end example + +@noindent +(Note the uppercase @samp{I} in @code{Info-tagify}.) This creates an +Info file with a tag table that you can validate. + +The third step is to validate the Info file: + +@example +M-x Info-validate +@end example + +@noindent +(Note the uppercase @samp{I} in @code{Info-validate}.) +In brief, the steps are: + +@example +@group +C-u M-x texinfo-format-buffer +M-x Info-tagify +M-x Info-validate +@end group +@end example + +After you have validated the node structure, you can rerun +@code{texinfo-format-buffer} in the normal way so it will construct a +tag table and split the file automatically, or you can make the tag +table and split the file manually. + +@node Splitting +@subsection Splitting a File Manually +@cindex Splitting an Info file manually +@cindex Info file, splitting manually + +You should split a large file or else let the +@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it +for you automatically. (Generally you will let one of the formatting +commands do this job for you. @xref{Creating an Info File}.) + +The split-off files are called the indirect subfiles. + +Info files are split to save memory. With smaller files, Emacs does not +have make such a large buffer to hold the information. + +If an Info file has more than 30 nodes, you should also make a tag +table for it. @xref{Using @code{Info-validate}}, for information +about creating a tag table. (Again, tag tables are usually created +automatically by the formatting command; you only need to create a tag +table yourself if you are doing the job manually. Most likely, you +will do this for a large, unsplit file on which you have run +@code{Info-validate}.) + +Visit the Info file you wish to tagify and split and type the two +commands: + +@example +M-x Info-tagify +M-x Info-split +@end example + +@noindent +(Note that the @samp{I} in @samp{Info} is uppercase.) + +When you use the @code{Info-split} command, the buffer is modified into a +(small) Info file which lists the indirect subfiles. This file should be +saved in place of the original visited file. The indirect subfiles are +written in the same directory the original file is in, with names generated +by appending @samp{-} and a number to the original file name. + +The primary file still functions as an Info file, but it contains just +the tag table and a directory of subfiles. + + +@node Info Format Specification +@appendix Info Format Specification + +@cindex Info format specification +@cindex Specification of Info format +@cindex Definition of Info format + +Here we describe the technical details of the Info format. + +In this formal description, the characters @code{<>*()|=#} are used +for the language of the description itself. Other characters are +literal. The formal constructs used are typical: @code{<...>} +indicates a metavariable name, @samp{=} means definition, @samp{*} +repetition, @samp{?} optional, @samp{()} grouping, @samp{|} +alternation, @samp{#} comment. Exception: @samp{*} at the beginning +of a line is literal. + +In general, programs that read Info files should try to be +case-insensitive to keywords that occur in the file (for example, +@samp{Tag Table} and @samp{Tag table} should be equivalent) in order to +support Info-generating programs that use different capitalization. + +The sections in an Info file (such as nodes or tag tables) are separated +with a sequence: + +@example +(^L)?^_(^L)?^J +@end example + +@noindent +That is, a @samp{CTRL-_} character followed by a newline, with optional +formfeed characters. We refer to such sequences as @t{<separator>}. + +We specify literal parentheses (those that are part of the Info +format) with @t{<lparen>} and @t{<rparen>}, meaning the single +characters @samp{(} and @samp{)} respectively. We specify the +@samp{CTRL-?} character (character number 127) @t{<del>}. Finally, +the two-character sequence @samp{^@var{x}} means the single +character @samp{CTRL-@var{x}}, for any @var{x}. + +This format definition was written some 25 years after the Info format +was first devised. So in the event of conflicts between this +definition and actual practice, practice wins. It also assumes some +general knowledge of Texinfo; it is meant to be a guide for +implementors rather than a rigid technical standard. We often refer +back to other parts of this manual for examples and definitions, +rather than redundantly spelling out every detail. + +@menu +* General: Info Format General Layout. +* Text: Info Format Text Constructs. +@end menu + + +@node Info Format General Layout +@section Info Format General Layout + +This section describes the overall layout of Info manuals. + +@menu +* Whole: Info Format Whole Manual. Split vs.@: nonsplit manuals. +* Preamble: Info Format Preamble. +* Indirect: Info Format Indirect Table. +* Tag table: Info Format Tag Table. +* Local variables: Info Format Local Variables. +* Regular nodes: Info Format Regular Nodes. +@end menu + + +@node Info Format Whole Manual +@subheading Info Format: A Whole Manual + +@cindex Nonsplit manuals, Info format of +@cindex Split manuals, Info format of +@cindex Whole manual, in Info format + +To begin, an Info manual is either @dfn{nonsplit} (contained wholly +within a single file) or @dfn{split} (across several files). + +The syntax for a nonsplit manual is: + +@example + <nonsplit info file> = +<preamble> +<node>* +<tag table>? +<local variables>? +@end example + +When split, there is a @dfn{main file}, which contains only pointers +to the nodes given in other @dfn{subfiles}. The main file looks +like this: + +@example + <split info main file> = +<preamble> +<indirect table> +<tag table> +<local variables>? +@end example + +The subfiles in a split manual have the following syntax: + +@example + <split info subfile> = +<preamble> +<node>* +@end example + +Note that the tag table is not optional for split files, as it is used +with the indirect table to deduce which subfile a particular node is in. + + +@node Info Format Preamble +@subheading Info Format: Preamble + +@cindex Preamble, in Info format + +The @t{<preamble>} is text at the beginning of all output files. +It is not intended to be visible by default in an Info viewer, but +may be displayed upon user request. + +@example + <preamble> = +<identification> # "This is FILENAME, produced by ..." +<copying text> # Expansion of @@copying text. +<dir entries> # Derived from @@dircategory and @@direntry. +@end example + +@noindent +These pieces are: + +@table @t +@item <identification line> +An arbitrary string beginning the output file, followed by a blank +line. + +@item <copying text> +The expansion of a @code{@@copying} environment, if the manual has +one (@pxref{@code{@@copying}}). + +@item <dir entries> +The result of any @code{@@dircategory} and @code{@@direntry} +commands present in the manual (@pxref{Installing Dir Entries}). + +@end table + + +@node Info Format Indirect Table +@subheading Info Format: Indirect Table + +@cindex Indirect table, in Info format + +@example + <indirect table> = +<separator> +Indirect: +(<filename>: <bytepos>)* +@end example + +The indirect table is written to the main file in the case of split +output only. It specifies, as a decimal integer, the starting byte +position (zero-based) that the first node of each subfile would have if +the subfiles were concatenated together in order, not including the +top-level file. The first node of actual content is pointed to by the +first entry. + +As an example, suppose split output is generated for the GDB manual. +The top-level file @file{gdb.info} will contain something like this: + +@example +<separator> +Indirect: +gdb.info-1: 1878 +gdb.info-2: 295733 +... +@end example + +This tells Info viewers that the first node of the manual occurs at +byte 1878 of the file @file{gdb.info-1} (which would be after that file's +preamble.) The first node in the @file{gdb.info-2} subfile would start at +byte 295733 if @file{gdb.info-2} were appended to @file{gdb.info-1}, +including any preamble sections in both files. + +Unfortunately, Info-creating programs such as @code{makeinfo} have not +always implemented these rules perfectly, due to various bugs and +oversights. Therefore, robust Info viewers should fall back to +searching ``nearby'' the given position for a node, instead of +giving up immediately if the position is not exactly at a node beginning. + + +@node Info Format Tag Table +@subheading Info Format: Tag Table + +@cindex Tag table, in Info format + +@example + <tag table> = +<separator> +Tag Table: +(<lparen>Indirect<rparen>)? +(Node|Ref): <nodeid>^?<bytepos> +<separator> +End Tag Table +@end example + +The @samp{(Indirect)} line appears in the case of split output only. + +The tag table specifies the starting byte position of each node and anchor +in the file. In the case of split output, it is only written in the main +output file. + +Each line defines an identifier as either an anchor or a node, as +specified. For example, @samp{Node: Top^?1647} says that the node named +@samp{Top} starts at byte 1647 while @samp{Ref: Overview-Footnote-1^?30045} +says that the anchor named @samp{Overview-Footnote-1} starts at byte 30045. +It is an error to define the same identifier both ways. + +In the case of nonsplit output, the byte positions simply refer to the +location in the output file. In the case of split output, the byte +positions refer to an imaginary file created by concatenating all the +split files (but not the top-level file). See the previous section. + +Here is an example: + +@example +^_ +Tag Table: +Node: Top^?89 +Node: Ch1^?292 +^_ +End Tag Table +@end example + +@noindent +This specifies a manual with two nodes, `Top' and `Ch1', at byte +positions 89 and 292 respectively. Because the @samp{(Indirect)} line +is not present, the manual is not split. + +Preamble sections or other non-node sections of files do not have a tag +table entry. + + +@node Info Format Local Variables +@subheading Info Format: Local Variables + +@cindex Local variable section, in Info format + +The local variables section is optional and is currently used to give the +encoding information. It may be augmented in the future. + +@example + <local variables> = +<separator> +Local Variables: +coding: <encoding> +End: +@end example + +@xref{@code{@@documentencoding}}. + + +@node Info Format Regular Nodes +@subheading Info Format: Regular Nodes + +@cindex Info nodes, in Info format + +Regular nodes look like this: + +@example + <node> = +<separator> +File: <fn>, Node: <id1>, (Next: <id2>, )? (Prev: <id3>, )? Up: <id4> + +<general text, until the next ^_ or end-of-file> +@end example + +@noindent +At least one space or tab must be present after each colon and comma, +but any number of spaces are ignored. The @t{<id>} node identifiers have +following format: + +@example + <id> = (<lparen><infofile><rparen>)?(<del>?<nodename><del>?)? +| <id> = (<lparen><infofile><rparen>)?(<nodename>)? +@end example + +This @t{<node>} defines @t{<id1>} in file @t{<fn>}, which is typically +either @samp{manualname} or @samp{manualname.info}. No parenthesized +@t{<infofile>} component may appear within @t{<id1>}. + +Each of the identifiers after @code{Next}, @code{Prev} and @code{Up} +refer to nodes or anchors within a file. These pointers normally +refer within the same file, but @samp{(dir)} is often used to point to +the top-level dir file. If an @t{<infofile>} component is used then +the node name may be omitted, in which case the node identifier refers +to the @samp{Top} node within the referenced file. + +The @code{Next} and @code{Prev} pointers are optional. The @code{Up} +pointer is technically also optional, although most likely this +indicates a mistake in the node structuring. Conventionally, the +nodes are arranged to form a tree, but this is not a requirement of +the format. + +Node names containing periods, commas, colons or parentheses +(including @@-commands which produce any of these) can confuse +Info readers. +If it is necessary to refer to a node whose name contains any of +these, the @t{<nodename>} should be surrounded by a pair of @t{<del>} +characters. There is support in @command{makeinfo} for adding these +characters (@pxref{INFO_SPECIAL_CHARS_QUOTE}); however, we don't +recommend you make use of this support until such time as Info-reading +programs that recognize this syntax are common. @xref{Node Line +Requirements}. + +The use of non-ASCII characters in the names of nodes is permitted, +but can cause problems in cross-references between nodes in Info files +with different character encodings, and also when node names from many +different files are listed (for example, with the @option{--apropos} +option to the standalone Info browser), so we recommend avoiding them +whenever feasible. For example, prefer the use of the ASCII +apostrophe character (@t{'}) to Unicode directional quotes. + +The @t{<general text>} of the node can include the special constructs +described next. + + +@node Info Format Text Constructs +@section Info Format Text Constructs + +@cindex Info format text constructs +@cindex text constructs, Info format + +These special Info constructs can appear within the text of a node. + + +@node Info Format Menu +@subsection Info Format: Menu + +@cindex Menus, in Info format + +Conventionally menus appear at the end of nodes, but the Info format +places no restrictions on their location. + +@example + <menu> = +* Menu: +(<menu entry> | <menu comment>)* +@end example + +The parts of a @t{<menu entry>} are also described in @ref{Menu +Parts}. They have the same syntax as cross-references (@pxref{Info +Format Cross Reference}). Indices extend the menu format to specify the +destination line; @pxref{Info Format Printindex}. + +A @t{<menu comment>} is any line not beginning with @samp{*} that +appears either at the beginning of the menu or is separated from a +menu entry by one or more blank lines. These comments are intended to +be displayed as part of the menu, as-is (@pxref{Writing a Menu}). + + +@node Info Format Image +@subsection Info Format: Image + +@cindex Images, in Info format + +The @code{@@image} command results in the following special directive +within the Info file (@pxref{Images}): + +@example + <image> = +^@@^H[image src="<image file>" + (text="<txt file contents>")? + (alt="<alt text>")? +^@@^H] +@end example + +The line breaks and indentation in this description are editorial; the +whitespace between the different parts of the directive in Info files +is arbitrary. + +In the strings @t{<image file>}, @t{<txt file contents>} and @t{<alt +text>}, @samp{"} is quoted as @samp{\"} and @samp{\} is quoted as +@samp{\\}. The txt and alt specifications are optional. + +The @t{alt} value serves the same purpose as in HTML: A prose +description of the image. In text-only displays or speech systems, +for example, the @t{alt} value may be used instead of displaying the +(typically graphical) @t{<image file>}. + +The @t{<txt file contents>}, if present, should be taken as an ASCII +representation of the image, for possible use on a text-only display. + +The format does not prescribe the choice between displaying the +@t{<image file>}, the @t{<alt text>} or the @t{<txt file contents>}. + + +@node Info Format Printindex +@subsection Info Format: Printindex + +@cindex Indices, in Info format + +Indices in Info format are generally written as a menu +(@pxref{Indices}), but with an additional directive at the beginning +marking this as an index node: + +@example + <printindex> = +^@@^H[index^@@^H] +* Menu: + +<index entry>* +@end example + +The @t{<index entry>} items are similar to normal menu entries, but +the free-format description is replaced by the line number of where +the entries occurs in the text: + +@example + <index entry> = +* <entry text>: <entry node>. <lparen>line <lineno><rparen> +@end example + +@noindent +The @t{<entry text>} is the index term. The @t{<lineno>} is an +unsigned integer, given relative to the start of the @t{<entry node>}. +There may be arbitrary whitespace after the colon and period, as usual +in menus, and may be broken across lines. Here is an example: + +@example +^@@^H[index^@@^H] +* Menu: + +* thunder: Weather Phenomena. (line 5) +@end example + +This means that an index entry for `thunder' appears at line 5 of the +node `Weather Phenomena'. + + +@node Info Format Cross Reference +@subsection Info Format: Cross-reference + +@cindex Cross-references, in Info format + +A general cross-reference in Info format has one of the following two forms: + +@example + <cross-reference> = + * (N|n)ote <id>:: +@c| * (N|n)ote <label>:<id>(.|,)? +| * (N|n)ote <label>:<id>(.|,) + + <id> = (<lparen><infofile><rparen>)?(<del>?<nodename><del>?)? +| <id> = (<lparen><infofile><rparen>)?(<nodename>)? + <label> = <del>?<label text><del>? +@end example + +No space should occur between the @samp{*} character and the following +@samp{N} or @samp{n}. @samp{*Note} should be used at the start of a +sentence, otherwise @samp{*note} should be used. (Some Info readers, +such as the one in Emacs, can display @samp{*Note} and @samp{*note} as +@samp{See} and @samp{see} respectively.) In both cases, @t{<label +text>} is descriptive text. + +In both forms the @t{<id>} refers to a node or anchor, in the same way +as a reference in the node information line does (@pxref{Info Format +Regular Nodes}). The optional parenthesized @samp{<infofile>} is the +filename of the manual being referenced, and the @t{<nodename>} is the +node or anchor within that manual, + +The second form has a descriptive label. A cross-reference in this form +should usually be terminated with a comma or period, to make it +feasible to find the end of the @t{<id>}. + +If @t{<label>} contains a colon character (@t{:}), it should be +surrounded with a pair of @t{<del>} characters. Likewise, if +@t{<nodename>} contains problematic characters (such as commas or +periods), it should be surrounded by a pair of @t{<del>} characters; +then a terminating comma or period is not needed. + +As with node names, this quoting mechanism has as of the time of +writing limited support in Info-reading programs; hence we do not +recommend using it until this changes. + +The format does not prescribe how to find other manuals to resolve +such references. + +Here are some examples: + +@example +*note GNU Free Documentation License:: +*note Tag table: Info Format Tag Table, for details. +*Note Overview: (make)Top. +*Note ^?:^?: (bash)Bourne Shell Builtins. +*Note alloca.h: (gnulib)^?alloca.h^?. +@end example + +The first shows a reference to a node in the current manual using the +short form. + +The second also refers to a node in the current manual, namely `Info +Format Tag Table'; the `Tag table' before the @samp{:} is only a label +on this particular reference, and the @samp{for details.} is text +belonging to the sentence, not part of the reference. + +The third example refers to the node `Top' in another manual, namely +@samp{make}, with `Overview' being the label for this cross-reference. + +The fourth example shows a colon character being quoted in a label, +and the fifth example shows a period being quoted in a node name. + +@xref{Cross References}. + + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@include fdl.texi + + +@node Command and Variable Index +@unnumbered Command and Variable Index + +This is an alphabetical list of all the @@-commands, assorted Emacs Lisp +functions, and several variables. To make the list easier to use, the +commands are listed without their preceding @samp{@@}. + +@printindex fn + + +@node General Index +@unnumbered General Index + +@printindex cp + + +@bye diff --git a/macros/texinfo/texinfo/doc/tp_api/Makefile.am b/macros/texinfo/texinfo/doc/tp_api/Makefile.am new file mode 100644 index 0000000000..805ac2a39a --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/Makefile.am @@ -0,0 +1,50 @@ +# $Id$ +# Makefile.am for texinfo/doc/tp_api. +# +# Copyright 2012-2019 Free Software Foundation, Inc. +# +# This file is free software; as a special exception the author gives +# unlimited permission to copy and/or distribute it, with or without +# modifications, as long as this notice is preserved. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the +# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +# Use the programs built in our distribution, taking account of possible +# cross-compiling. +MAKEINFO = $(PERL) -I $(top_srcdir)/tp/ $(top_srcdir)/tp/texi2any.pl + +if BUILD_PERL_API_TEXI + +dist_info_TEXINFOS = tp_api.texi +#info_TEXINFOS_SOURCES = tp_api.texi +tp_api_TEXINFOS = tp_api.texi +#dist_tp_api_TEXINFOS = tp_api.texi +#tp_api_SOURCES = tp_api.texi + +BUILT_SOURCES = tp_api.texi + +#DISTCLEANFILES = tp_api.info + +tp_api_dependencies = \ + $(top_srcdir)/tp/Texinfo/Common.pm $(top_srcdir)/tp/Texinfo/ParserNonXS.pm \ + $(top_srcdir)/tp/Texinfo/Structuring.pm $(top_srcdir)/tp/Texinfo/Report.pm \ + $(top_srcdir)/tp/Texinfo/Encoding.pm \ + $(top_srcdir)/tp/Texinfo/Convert/NodeNameNormalization.pm \ + $(top_srcdir)/tp/Texinfo/Convert/Text.pm \ + $(top_srcdir)/tp/Texinfo/Convert/Texinfo.pm \ + $(top_srcdir)/tp/Texinfo/Convert/Converter.pm \ + $(top_srcdir)/tp/Texinfo/Convert/Unicode.pm \ + $(top_srcdir)/tp/Texinfo/Convert/Info.pm \ + $(top_srcdir)/tp/Texinfo/Convert/DocBook.pm \ + $(top_srcdir)/tp/Texinfo/Convert/TexinfoXML.pm \ + $(top_srcdir)/tp/Texinfo/Convert/Plaintext.pm \ + $(top_srcdir)/tp/Texinfo/Convert/HTML.pm + +tp_api.texi: $(tp_api_dependencies) + $(PERL) -I $(top_srcdir)/Pod-Simple-Texinfo/lib/ -I $(top_srcdir)/tp/ -I $(top_srcdir)/tp/maintain/lib/Text-Unidecode/lib/ -I $(top_srcdir)/tp/maintain/lib/libintl-perl/lib/ -I $(top_srcdir)/tp/maintain/lib/Unicode-EastAsianWidth/lib/ $(top_srcdir)/Pod-Simple-Texinfo/pod2texi.pl --base-level=section --top 'Texinfo perl module' --subdir=api_includes -o $@ $(tp_api_dependencies) + +EXTRA_DIST = api_includes tp_api.texi + +endif diff --git a/macros/texinfo/texinfo/doc/tp_api/Makefile.in b/macros/texinfo/texinfo/doc/tp_api/Makefile.in new file mode 100644 index 0000000000..f6f0e281ad --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/Makefile.in @@ -0,0 +1,1242 @@ +# Makefile.in generated by automake 1.16 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2018 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# $Id$ +# Makefile.am for texinfo/doc/tp_api. +# +# Copyright 2012-2019 Free Software Foundation, Inc. +# +# This file is free software; as a special exception the author gives +# unlimited permission to copy and/or distribute it, with or without +# modifications, as long as this notice is preserved. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the +# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +VPATH = @srcdir@ +am__is_gnu_make = { \ + if test -z '$(MAKELEVEL)'; then \ + false; \ + elif test -n '$(MAKE_HOST)'; then \ + true; \ + elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ + true; \ + else \ + false; \ + fi; \ +} +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc/tp_api +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/gnulib/m4/00gnulib.m4 \ + $(top_srcdir)/gnulib/m4/__inline.m4 \ + $(top_srcdir)/gnulib/m4/absolute-header.m4 \ + $(top_srcdir)/gnulib/m4/alloca.m4 \ + $(top_srcdir)/gnulib/m4/argz.m4 \ + $(top_srcdir)/gnulib/m4/btowc.m4 \ + $(top_srcdir)/gnulib/m4/builtin-expect.m4 \ + $(top_srcdir)/gnulib/m4/codeset.m4 \ + $(top_srcdir)/gnulib/m4/dirname.m4 \ + $(top_srcdir)/gnulib/m4/double-slash-root.m4 \ + $(top_srcdir)/gnulib/m4/eealloc.m4 \ + $(top_srcdir)/gnulib/m4/errno_h.m4 \ + $(top_srcdir)/gnulib/m4/error.m4 \ + $(top_srcdir)/gnulib/m4/exponentd.m4 \ + $(top_srcdir)/gnulib/m4/extensions.m4 \ + $(top_srcdir)/gnulib/m4/extern-inline.m4 \ + $(top_srcdir)/gnulib/m4/float_h.m4 \ + $(top_srcdir)/gnulib/m4/getopt.m4 \ + $(top_srcdir)/gnulib/m4/getprogname.m4 \ + $(top_srcdir)/gnulib/m4/gettext.m4 \ + $(top_srcdir)/gnulib/m4/glibc21.m4 \ + $(top_srcdir)/gnulib/m4/gnulib-common.m4 \ + $(top_srcdir)/gnulib/m4/gnulib-comp.m4 \ + $(top_srcdir)/gnulib/m4/host-cpu-c-abi.m4 \ + $(top_srcdir)/gnulib/m4/iconv.m4 \ + $(top_srcdir)/gnulib/m4/include_next.m4 \ + $(top_srcdir)/gnulib/m4/intlmacosx.m4 \ + $(top_srcdir)/gnulib/m4/intmax_t.m4 \ + $(top_srcdir)/gnulib/m4/inttypes_h.m4 \ + $(top_srcdir)/gnulib/m4/iswblank.m4 \ + $(top_srcdir)/gnulib/m4/langinfo_h.m4 \ + $(top_srcdir)/gnulib/m4/lib-ld.m4 \ + $(top_srcdir)/gnulib/m4/lib-link.m4 \ + $(top_srcdir)/gnulib/m4/lib-prefix.m4 \ + $(top_srcdir)/gnulib/m4/libunistring-base.m4 \ + $(top_srcdir)/gnulib/m4/limits-h.m4 \ + $(top_srcdir)/gnulib/m4/localcharset.m4 \ + $(top_srcdir)/gnulib/m4/locale-fr.m4 \ + $(top_srcdir)/gnulib/m4/locale-ja.m4 \ + $(top_srcdir)/gnulib/m4/locale-zh.m4 \ + $(top_srcdir)/gnulib/m4/locale_h.m4 \ + $(top_srcdir)/gnulib/m4/localeconv.m4 \ + $(top_srcdir)/gnulib/m4/lock.m4 \ + $(top_srcdir)/gnulib/m4/longlong.m4 \ + $(top_srcdir)/gnulib/m4/malloc.m4 \ + $(top_srcdir)/gnulib/m4/malloca.m4 \ + $(top_srcdir)/gnulib/m4/mbchar.m4 \ + $(top_srcdir)/gnulib/m4/mbiter.m4 \ + $(top_srcdir)/gnulib/m4/mbrtowc.m4 \ + $(top_srcdir)/gnulib/m4/mbsinit.m4 \ + $(top_srcdir)/gnulib/m4/mbslen.m4 \ + $(top_srcdir)/gnulib/m4/mbstate_t.m4 \ + $(top_srcdir)/gnulib/m4/mbswidth.m4 \ + $(top_srcdir)/gnulib/m4/mbtowc.m4 \ + $(top_srcdir)/gnulib/m4/memchr.m4 \ + $(top_srcdir)/gnulib/m4/mempcpy.m4 \ + $(top_srcdir)/gnulib/m4/memrchr.m4 \ + $(top_srcdir)/gnulib/m4/mmap-anon.m4 \ + $(top_srcdir)/gnulib/m4/msvc-inval.m4 \ + $(top_srcdir)/gnulib/m4/msvc-nothrow.m4 \ + $(top_srcdir)/gnulib/m4/multiarch.m4 \ + $(top_srcdir)/gnulib/m4/nl_langinfo.m4 \ + $(top_srcdir)/gnulib/m4/nls.m4 \ + $(top_srcdir)/gnulib/m4/nocrash.m4 \ + $(top_srcdir)/gnulib/m4/off_t.m4 $(top_srcdir)/gnulib/m4/po.m4 \ + $(top_srcdir)/gnulib/m4/printf.m4 \ + $(top_srcdir)/gnulib/m4/progtest.m4 \ + $(top_srcdir)/gnulib/m4/pthread_rwlock_rdlock.m4 \ + $(top_srcdir)/gnulib/m4/regex.m4 \ + $(top_srcdir)/gnulib/m4/size_max.m4 \ + $(top_srcdir)/gnulib/m4/ssize_t.m4 \ + $(top_srcdir)/gnulib/m4/stdarg.m4 \ + $(top_srcdir)/gnulib/m4/stdbool.m4 \ + $(top_srcdir)/gnulib/m4/stddef_h.m4 \ + $(top_srcdir)/gnulib/m4/stdint.m4 \ + $(top_srcdir)/gnulib/m4/stdint_h.m4 \ + $(top_srcdir)/gnulib/m4/stdio_h.m4 \ + $(top_srcdir)/gnulib/m4/stdlib_h.m4 \ + $(top_srcdir)/gnulib/m4/stpcpy.m4 \ + $(top_srcdir)/gnulib/m4/strcase.m4 \ + $(top_srcdir)/gnulib/m4/strcasestr.m4 \ + $(top_srcdir)/gnulib/m4/strdup.m4 \ + $(top_srcdir)/gnulib/m4/strerror.m4 \ + $(top_srcdir)/gnulib/m4/string_h.m4 \ + $(top_srcdir)/gnulib/m4/strings_h.m4 \ + $(top_srcdir)/gnulib/m4/strndup.m4 \ + $(top_srcdir)/gnulib/m4/strnlen.m4 \ + $(top_srcdir)/gnulib/m4/strstr.m4 \ + $(top_srcdir)/gnulib/m4/sys_socket_h.m4 \ + $(top_srcdir)/gnulib/m4/sys_types_h.m4 \ + $(top_srcdir)/gnulib/m4/threadlib.m4 \ + $(top_srcdir)/gnulib/m4/unistd_h.m4 \ + $(top_srcdir)/gnulib/m4/vasnprintf.m4 \ + $(top_srcdir)/gnulib/m4/vasprintf.m4 \ + $(top_srcdir)/gnulib/m4/warn-on-use.m4 \ + $(top_srcdir)/gnulib/m4/wchar_h.m4 \ + $(top_srcdir)/gnulib/m4/wchar_t.m4 \ + $(top_srcdir)/gnulib/m4/wcrtomb.m4 \ + $(top_srcdir)/gnulib/m4/wctype_h.m4 \ + $(top_srcdir)/gnulib/m4/wcwidth.m4 \ + $(top_srcdir)/gnulib/m4/wint_t.m4 \ + $(top_srcdir)/gnulib/m4/xalloc.m4 \ + $(top_srcdir)/gnulib/m4/xsize.m4 $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +SOURCES = +DIST_SOURCES = +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +am__DIST_COMMON = $(srcdir)/Makefile.in +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +ALLOCA = @ALLOCA@ +ALLOCA_H = @ALLOCA_H@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +APPLE_UNIVERSAL_BUILD = @APPLE_UNIVERSAL_BUILD@ +AR = @AR@ +ARFLAGS = @ARFLAGS@ +ARGZ_H = @ARGZ_H@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BITSIZEOF_PTRDIFF_T = @BITSIZEOF_PTRDIFF_T@ +BITSIZEOF_SIG_ATOMIC_T = @BITSIZEOF_SIG_ATOMIC_T@ +BITSIZEOF_SIZE_T = @BITSIZEOF_SIZE_T@ +BITSIZEOF_WCHAR_T = @BITSIZEOF_WCHAR_T@ +BITSIZEOF_WINT_T = @BITSIZEOF_WINT_T@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DIFF_A_OPTION = @DIFF_A_OPTION@ +DIFF_U_OPTION = @DIFF_U_OPTION@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EMULTIHOP_HIDDEN = @EMULTIHOP_HIDDEN@ +EMULTIHOP_VALUE = @EMULTIHOP_VALUE@ +ENOLINK_HIDDEN = @ENOLINK_HIDDEN@ +ENOLINK_VALUE = @ENOLINK_VALUE@ +EOVERFLOW_HIDDEN = @EOVERFLOW_HIDDEN@ +EOVERFLOW_VALUE = @EOVERFLOW_VALUE@ +ERRNO_H = @ERRNO_H@ +EXEEXT = @EXEEXT@ +FLOAT_H = @FLOAT_H@ +GAWK = @GAWK@ +GETOPT_CDEFS_H = @GETOPT_CDEFS_H@ +GETOPT_H = @GETOPT_H@ +GETTEXT_MACRO_VERSION = @GETTEXT_MACRO_VERSION@ +GLIBC21 = @GLIBC21@ +GMSGFMT = @GMSGFMT@ +GMSGFMT_015 = @GMSGFMT_015@ +GNULIB_ATOLL = @GNULIB_ATOLL@ +GNULIB_BTOWC = @GNULIB_BTOWC@ +GNULIB_CALLOC_POSIX = @GNULIB_CALLOC_POSIX@ +GNULIB_CANONICALIZE_FILE_NAME = @GNULIB_CANONICALIZE_FILE_NAME@ +GNULIB_CHDIR = @GNULIB_CHDIR@ +GNULIB_CHOWN = @GNULIB_CHOWN@ +GNULIB_CLOSE = @GNULIB_CLOSE@ +GNULIB_DPRINTF = @GNULIB_DPRINTF@ +GNULIB_DUP = @GNULIB_DUP@ +GNULIB_DUP2 = @GNULIB_DUP2@ +GNULIB_DUP3 = @GNULIB_DUP3@ +GNULIB_DUPLOCALE = @GNULIB_DUPLOCALE@ +GNULIB_ENVIRON = @GNULIB_ENVIRON@ +GNULIB_EUIDACCESS = @GNULIB_EUIDACCESS@ +GNULIB_EXPLICIT_BZERO = @GNULIB_EXPLICIT_BZERO@ +GNULIB_FACCESSAT = @GNULIB_FACCESSAT@ +GNULIB_FCHDIR = @GNULIB_FCHDIR@ +GNULIB_FCHOWNAT = @GNULIB_FCHOWNAT@ +GNULIB_FCLOSE = @GNULIB_FCLOSE@ +GNULIB_FDATASYNC = @GNULIB_FDATASYNC@ +GNULIB_FDOPEN = @GNULIB_FDOPEN@ +GNULIB_FFLUSH = @GNULIB_FFLUSH@ +GNULIB_FFS = @GNULIB_FFS@ +GNULIB_FFSL = @GNULIB_FFSL@ +GNULIB_FFSLL = @GNULIB_FFSLL@ +GNULIB_FGETC = @GNULIB_FGETC@ +GNULIB_FGETS = @GNULIB_FGETS@ +GNULIB_FOPEN = @GNULIB_FOPEN@ +GNULIB_FPRINTF = @GNULIB_FPRINTF@ +GNULIB_FPRINTF_POSIX = @GNULIB_FPRINTF_POSIX@ +GNULIB_FPURGE = @GNULIB_FPURGE@ +GNULIB_FPUTC = @GNULIB_FPUTC@ +GNULIB_FPUTS = @GNULIB_FPUTS@ +GNULIB_FREAD = @GNULIB_FREAD@ +GNULIB_FREOPEN = @GNULIB_FREOPEN@ +GNULIB_FSCANF = @GNULIB_FSCANF@ +GNULIB_FSEEK = @GNULIB_FSEEK@ +GNULIB_FSEEKO = @GNULIB_FSEEKO@ +GNULIB_FSYNC = @GNULIB_FSYNC@ +GNULIB_FTELL = @GNULIB_FTELL@ +GNULIB_FTELLO = @GNULIB_FTELLO@ +GNULIB_FTRUNCATE = @GNULIB_FTRUNCATE@ +GNULIB_FWRITE = @GNULIB_FWRITE@ +GNULIB_GETC = @GNULIB_GETC@ +GNULIB_GETCHAR = @GNULIB_GETCHAR@ +GNULIB_GETCWD = @GNULIB_GETCWD@ +GNULIB_GETDELIM = @GNULIB_GETDELIM@ +GNULIB_GETDOMAINNAME = @GNULIB_GETDOMAINNAME@ +GNULIB_GETDTABLESIZE = @GNULIB_GETDTABLESIZE@ +GNULIB_GETGROUPS = @GNULIB_GETGROUPS@ +GNULIB_GETHOSTNAME = @GNULIB_GETHOSTNAME@ +GNULIB_GETLINE = @GNULIB_GETLINE@ +GNULIB_GETLOADAVG = @GNULIB_GETLOADAVG@ +GNULIB_GETLOGIN = @GNULIB_GETLOGIN@ +GNULIB_GETLOGIN_R = @GNULIB_GETLOGIN_R@ +GNULIB_GETPAGESIZE = @GNULIB_GETPAGESIZE@ +GNULIB_GETPASS = @GNULIB_GETPASS@ +GNULIB_GETSUBOPT = @GNULIB_GETSUBOPT@ +GNULIB_GETUSERSHELL = @GNULIB_GETUSERSHELL@ +GNULIB_GL_UNISTD_H_GETOPT = @GNULIB_GL_UNISTD_H_GETOPT@ +GNULIB_GRANTPT = @GNULIB_GRANTPT@ +GNULIB_GROUP_MEMBER = @GNULIB_GROUP_MEMBER@ +GNULIB_ISATTY = @GNULIB_ISATTY@ +GNULIB_ISWBLANK = @GNULIB_ISWBLANK@ +GNULIB_ISWCTYPE = @GNULIB_ISWCTYPE@ +GNULIB_LCHOWN = @GNULIB_LCHOWN@ +GNULIB_LINK = @GNULIB_LINK@ +GNULIB_LINKAT = @GNULIB_LINKAT@ +GNULIB_LOCALECONV = @GNULIB_LOCALECONV@ +GNULIB_LOCALENAME = @GNULIB_LOCALENAME@ +GNULIB_LSEEK = @GNULIB_LSEEK@ +GNULIB_MALLOC_POSIX = @GNULIB_MALLOC_POSIX@ +GNULIB_MBRLEN = @GNULIB_MBRLEN@ +GNULIB_MBRTOWC = @GNULIB_MBRTOWC@ +GNULIB_MBSCASECMP = @GNULIB_MBSCASECMP@ +GNULIB_MBSCASESTR = @GNULIB_MBSCASESTR@ +GNULIB_MBSCHR = @GNULIB_MBSCHR@ +GNULIB_MBSCSPN = @GNULIB_MBSCSPN@ +GNULIB_MBSINIT = @GNULIB_MBSINIT@ +GNULIB_MBSLEN = @GNULIB_MBSLEN@ +GNULIB_MBSNCASECMP = @GNULIB_MBSNCASECMP@ +GNULIB_MBSNLEN = @GNULIB_MBSNLEN@ +GNULIB_MBSNRTOWCS = @GNULIB_MBSNRTOWCS@ +GNULIB_MBSPBRK = @GNULIB_MBSPBRK@ +GNULIB_MBSPCASECMP = @GNULIB_MBSPCASECMP@ +GNULIB_MBSRCHR = @GNULIB_MBSRCHR@ +GNULIB_MBSRTOWCS = @GNULIB_MBSRTOWCS@ +GNULIB_MBSSEP = @GNULIB_MBSSEP@ +GNULIB_MBSSPN = @GNULIB_MBSSPN@ +GNULIB_MBSSTR = @GNULIB_MBSSTR@ +GNULIB_MBSTOK_R = @GNULIB_MBSTOK_R@ +GNULIB_MBTOWC = @GNULIB_MBTOWC@ +GNULIB_MEMCHR = @GNULIB_MEMCHR@ +GNULIB_MEMMEM = @GNULIB_MEMMEM@ +GNULIB_MEMPCPY = @GNULIB_MEMPCPY@ +GNULIB_MEMRCHR = @GNULIB_MEMRCHR@ +GNULIB_MKDTEMP = @GNULIB_MKDTEMP@ +GNULIB_MKOSTEMP = @GNULIB_MKOSTEMP@ +GNULIB_MKOSTEMPS = @GNULIB_MKOSTEMPS@ +GNULIB_MKSTEMP = @GNULIB_MKSTEMP@ +GNULIB_MKSTEMPS = @GNULIB_MKSTEMPS@ +GNULIB_NL_LANGINFO = @GNULIB_NL_LANGINFO@ +GNULIB_OBSTACK_PRINTF = @GNULIB_OBSTACK_PRINTF@ +GNULIB_OBSTACK_PRINTF_POSIX = @GNULIB_OBSTACK_PRINTF_POSIX@ +GNULIB_OVERRIDES_WINT_T = @GNULIB_OVERRIDES_WINT_T@ +GNULIB_PCLOSE = @GNULIB_PCLOSE@ +GNULIB_PERROR = @GNULIB_PERROR@ +GNULIB_PIPE = @GNULIB_PIPE@ +GNULIB_PIPE2 = @GNULIB_PIPE2@ +GNULIB_POPEN = @GNULIB_POPEN@ +GNULIB_POSIX_OPENPT = @GNULIB_POSIX_OPENPT@ +GNULIB_PREAD = @GNULIB_PREAD@ +GNULIB_PRINTF = @GNULIB_PRINTF@ +GNULIB_PRINTF_POSIX = @GNULIB_PRINTF_POSIX@ +GNULIB_PTSNAME = @GNULIB_PTSNAME@ +GNULIB_PTSNAME_R = @GNULIB_PTSNAME_R@ +GNULIB_PUTC = @GNULIB_PUTC@ +GNULIB_PUTCHAR = @GNULIB_PUTCHAR@ +GNULIB_PUTENV = @GNULIB_PUTENV@ +GNULIB_PUTS = @GNULIB_PUTS@ +GNULIB_PWRITE = @GNULIB_PWRITE@ +GNULIB_QSORT_R = @GNULIB_QSORT_R@ +GNULIB_RANDOM = @GNULIB_RANDOM@ +GNULIB_RANDOM_R = @GNULIB_RANDOM_R@ +GNULIB_RAWMEMCHR = @GNULIB_RAWMEMCHR@ +GNULIB_READ = @GNULIB_READ@ +GNULIB_READLINK = @GNULIB_READLINK@ +GNULIB_READLINKAT = @GNULIB_READLINKAT@ +GNULIB_REALLOCARRAY = @GNULIB_REALLOCARRAY@ +GNULIB_REALLOC_POSIX = @GNULIB_REALLOC_POSIX@ +GNULIB_REALPATH = @GNULIB_REALPATH@ +GNULIB_REMOVE = @GNULIB_REMOVE@ +GNULIB_RENAME = @GNULIB_RENAME@ +GNULIB_RENAMEAT = @GNULIB_RENAMEAT@ +GNULIB_RMDIR = @GNULIB_RMDIR@ +GNULIB_RPMATCH = @GNULIB_RPMATCH@ +GNULIB_SCANF = @GNULIB_SCANF@ +GNULIB_SECURE_GETENV = @GNULIB_SECURE_GETENV@ +GNULIB_SETENV = @GNULIB_SETENV@ +GNULIB_SETHOSTNAME = @GNULIB_SETHOSTNAME@ +GNULIB_SETLOCALE = @GNULIB_SETLOCALE@ +GNULIB_SLEEP = @GNULIB_SLEEP@ +GNULIB_SNPRINTF = @GNULIB_SNPRINTF@ +GNULIB_SPRINTF_POSIX = @GNULIB_SPRINTF_POSIX@ +GNULIB_STDIO_H_NONBLOCKING = @GNULIB_STDIO_H_NONBLOCKING@ +GNULIB_STDIO_H_SIGPIPE = @GNULIB_STDIO_H_SIGPIPE@ +GNULIB_STPCPY = @GNULIB_STPCPY@ +GNULIB_STPNCPY = @GNULIB_STPNCPY@ +GNULIB_STRCASESTR = @GNULIB_STRCASESTR@ +GNULIB_STRCHRNUL = @GNULIB_STRCHRNUL@ +GNULIB_STRDUP = @GNULIB_STRDUP@ +GNULIB_STRERROR = @GNULIB_STRERROR@ +GNULIB_STRERROR_R = @GNULIB_STRERROR_R@ +GNULIB_STRNCAT = @GNULIB_STRNCAT@ +GNULIB_STRNDUP = @GNULIB_STRNDUP@ +GNULIB_STRNLEN = @GNULIB_STRNLEN@ +GNULIB_STRPBRK = @GNULIB_STRPBRK@ +GNULIB_STRSEP = @GNULIB_STRSEP@ +GNULIB_STRSIGNAL = @GNULIB_STRSIGNAL@ +GNULIB_STRSTR = @GNULIB_STRSTR@ +GNULIB_STRTOD = @GNULIB_STRTOD@ +GNULIB_STRTOK_R = @GNULIB_STRTOK_R@ +GNULIB_STRTOLL = @GNULIB_STRTOLL@ +GNULIB_STRTOULL = @GNULIB_STRTOULL@ +GNULIB_STRVERSCMP = @GNULIB_STRVERSCMP@ +GNULIB_SYMLINK = @GNULIB_SYMLINK@ +GNULIB_SYMLINKAT = @GNULIB_SYMLINKAT@ +GNULIB_SYSTEM_POSIX = @GNULIB_SYSTEM_POSIX@ +GNULIB_TMPFILE = @GNULIB_TMPFILE@ +GNULIB_TOWCTRANS = @GNULIB_TOWCTRANS@ +GNULIB_TRUNCATE = @GNULIB_TRUNCATE@ +GNULIB_TTYNAME_R = @GNULIB_TTYNAME_R@ +GNULIB_UNISTD_H_NONBLOCKING = @GNULIB_UNISTD_H_NONBLOCKING@ +GNULIB_UNISTD_H_SIGPIPE = @GNULIB_UNISTD_H_SIGPIPE@ +GNULIB_UNLINK = @GNULIB_UNLINK@ +GNULIB_UNLINKAT = @GNULIB_UNLINKAT@ +GNULIB_UNLOCKPT = @GNULIB_UNLOCKPT@ +GNULIB_UNSETENV = @GNULIB_UNSETENV@ +GNULIB_USLEEP = @GNULIB_USLEEP@ +GNULIB_VASPRINTF = @GNULIB_VASPRINTF@ +GNULIB_VDPRINTF = @GNULIB_VDPRINTF@ +GNULIB_VFPRINTF = @GNULIB_VFPRINTF@ +GNULIB_VFPRINTF_POSIX = @GNULIB_VFPRINTF_POSIX@ +GNULIB_VFSCANF = @GNULIB_VFSCANF@ +GNULIB_VPRINTF = @GNULIB_VPRINTF@ +GNULIB_VPRINTF_POSIX = @GNULIB_VPRINTF_POSIX@ +GNULIB_VSCANF = @GNULIB_VSCANF@ +GNULIB_VSNPRINTF = @GNULIB_VSNPRINTF@ +GNULIB_VSPRINTF_POSIX = @GNULIB_VSPRINTF_POSIX@ +GNULIB_WCPCPY = @GNULIB_WCPCPY@ +GNULIB_WCPNCPY = @GNULIB_WCPNCPY@ +GNULIB_WCRTOMB = @GNULIB_WCRTOMB@ +GNULIB_WCSCASECMP = @GNULIB_WCSCASECMP@ +GNULIB_WCSCAT = @GNULIB_WCSCAT@ +GNULIB_WCSCHR = @GNULIB_WCSCHR@ +GNULIB_WCSCMP = @GNULIB_WCSCMP@ +GNULIB_WCSCOLL = @GNULIB_WCSCOLL@ +GNULIB_WCSCPY = @GNULIB_WCSCPY@ +GNULIB_WCSCSPN = @GNULIB_WCSCSPN@ +GNULIB_WCSDUP = @GNULIB_WCSDUP@ +GNULIB_WCSFTIME = @GNULIB_WCSFTIME@ +GNULIB_WCSLEN = @GNULIB_WCSLEN@ +GNULIB_WCSNCASECMP = @GNULIB_WCSNCASECMP@ +GNULIB_WCSNCAT = @GNULIB_WCSNCAT@ +GNULIB_WCSNCMP = @GNULIB_WCSNCMP@ +GNULIB_WCSNCPY = @GNULIB_WCSNCPY@ +GNULIB_WCSNLEN = @GNULIB_WCSNLEN@ +GNULIB_WCSNRTOMBS = @GNULIB_WCSNRTOMBS@ +GNULIB_WCSPBRK = @GNULIB_WCSPBRK@ +GNULIB_WCSRCHR = @GNULIB_WCSRCHR@ +GNULIB_WCSRTOMBS = @GNULIB_WCSRTOMBS@ +GNULIB_WCSSPN = @GNULIB_WCSSPN@ +GNULIB_WCSSTR = @GNULIB_WCSSTR@ +GNULIB_WCSTOK = @GNULIB_WCSTOK@ +GNULIB_WCSWIDTH = @GNULIB_WCSWIDTH@ +GNULIB_WCSXFRM = @GNULIB_WCSXFRM@ +GNULIB_WCTOB = @GNULIB_WCTOB@ +GNULIB_WCTOMB = @GNULIB_WCTOMB@ +GNULIB_WCTRANS = @GNULIB_WCTRANS@ +GNULIB_WCTYPE = @GNULIB_WCTYPE@ +GNULIB_WCWIDTH = @GNULIB_WCWIDTH@ +GNULIB_WMEMCHR = @GNULIB_WMEMCHR@ +GNULIB_WMEMCMP = @GNULIB_WMEMCMP@ +GNULIB_WMEMCPY = @GNULIB_WMEMCPY@ +GNULIB_WMEMMOVE = @GNULIB_WMEMMOVE@ +GNULIB_WMEMSET = @GNULIB_WMEMSET@ +GNULIB_WRITE = @GNULIB_WRITE@ +GNULIB__EXIT = @GNULIB__EXIT@ +GREP = @GREP@ +HAVE_ATOLL = @HAVE_ATOLL@ +HAVE_BTOWC = @HAVE_BTOWC@ +HAVE_C99_STDINT_H = @HAVE_C99_STDINT_H@ +HAVE_CANONICALIZE_FILE_NAME = @HAVE_CANONICALIZE_FILE_NAME@ +HAVE_CHOWN = @HAVE_CHOWN@ +HAVE_CRTDEFS_H = @HAVE_CRTDEFS_H@ +HAVE_DECL_ENVIRON = @HAVE_DECL_ENVIRON@ +HAVE_DECL_FCHDIR = @HAVE_DECL_FCHDIR@ +HAVE_DECL_FDATASYNC = @HAVE_DECL_FDATASYNC@ +HAVE_DECL_FPURGE = @HAVE_DECL_FPURGE@ +HAVE_DECL_FSEEKO = @HAVE_DECL_FSEEKO@ +HAVE_DECL_FTELLO = @HAVE_DECL_FTELLO@ +HAVE_DECL_GETDELIM = @HAVE_DECL_GETDELIM@ +HAVE_DECL_GETDOMAINNAME = @HAVE_DECL_GETDOMAINNAME@ +HAVE_DECL_GETLINE = @HAVE_DECL_GETLINE@ +HAVE_DECL_GETLOADAVG = @HAVE_DECL_GETLOADAVG@ +HAVE_DECL_GETLOGIN = @HAVE_DECL_GETLOGIN@ +HAVE_DECL_GETLOGIN_R = @HAVE_DECL_GETLOGIN_R@ +HAVE_DECL_GETPAGESIZE = @HAVE_DECL_GETPAGESIZE@ +HAVE_DECL_GETUSERSHELL = @HAVE_DECL_GETUSERSHELL@ +HAVE_DECL_INITSTATE = @HAVE_DECL_INITSTATE@ +HAVE_DECL_MEMMEM = @HAVE_DECL_MEMMEM@ +HAVE_DECL_MEMRCHR = @HAVE_DECL_MEMRCHR@ +HAVE_DECL_OBSTACK_PRINTF = @HAVE_DECL_OBSTACK_PRINTF@ +HAVE_DECL_SETENV = @HAVE_DECL_SETENV@ +HAVE_DECL_SETHOSTNAME = @HAVE_DECL_SETHOSTNAME@ +HAVE_DECL_SETSTATE = @HAVE_DECL_SETSTATE@ +HAVE_DECL_SNPRINTF = @HAVE_DECL_SNPRINTF@ +HAVE_DECL_STRDUP = @HAVE_DECL_STRDUP@ +HAVE_DECL_STRERROR_R = @HAVE_DECL_STRERROR_R@ +HAVE_DECL_STRNCASECMP = @HAVE_DECL_STRNCASECMP@ +HAVE_DECL_STRNDUP = @HAVE_DECL_STRNDUP@ +HAVE_DECL_STRNLEN = @HAVE_DECL_STRNLEN@ +HAVE_DECL_STRSIGNAL = @HAVE_DECL_STRSIGNAL@ +HAVE_DECL_STRTOK_R = @HAVE_DECL_STRTOK_R@ +HAVE_DECL_TRUNCATE = @HAVE_DECL_TRUNCATE@ +HAVE_DECL_TTYNAME_R = @HAVE_DECL_TTYNAME_R@ +HAVE_DECL_UNSETENV = @HAVE_DECL_UNSETENV@ +HAVE_DECL_VSNPRINTF = @HAVE_DECL_VSNPRINTF@ +HAVE_DECL_WCTOB = @HAVE_DECL_WCTOB@ +HAVE_DECL_WCWIDTH = @HAVE_DECL_WCWIDTH@ +HAVE_DPRINTF = @HAVE_DPRINTF@ +HAVE_DUP2 = @HAVE_DUP2@ +HAVE_DUP3 = @HAVE_DUP3@ +HAVE_DUPLOCALE = @HAVE_DUPLOCALE@ +HAVE_EUIDACCESS = @HAVE_EUIDACCESS@ +HAVE_EXPLICIT_BZERO = @HAVE_EXPLICIT_BZERO@ +HAVE_FACCESSAT = @HAVE_FACCESSAT@ +HAVE_FCHDIR = @HAVE_FCHDIR@ +HAVE_FCHOWNAT = @HAVE_FCHOWNAT@ +HAVE_FDATASYNC = @HAVE_FDATASYNC@ +HAVE_FEATURES_H = @HAVE_FEATURES_H@ +HAVE_FFS = @HAVE_FFS@ +HAVE_FFSL = @HAVE_FFSL@ +HAVE_FFSLL = @HAVE_FFSLL@ +HAVE_FREELOCALE = @HAVE_FREELOCALE@ +HAVE_FSEEKO = @HAVE_FSEEKO@ +HAVE_FSYNC = @HAVE_FSYNC@ +HAVE_FTELLO = @HAVE_FTELLO@ +HAVE_FTRUNCATE = @HAVE_FTRUNCATE@ +HAVE_GETDTABLESIZE = @HAVE_GETDTABLESIZE@ +HAVE_GETGROUPS = @HAVE_GETGROUPS@ +HAVE_GETHOSTNAME = @HAVE_GETHOSTNAME@ +HAVE_GETLOGIN = @HAVE_GETLOGIN@ +HAVE_GETOPT_H = @HAVE_GETOPT_H@ +HAVE_GETPAGESIZE = @HAVE_GETPAGESIZE@ +HAVE_GETPASS = @HAVE_GETPASS@ +HAVE_GETSUBOPT = @HAVE_GETSUBOPT@ +HAVE_GRANTPT = @HAVE_GRANTPT@ +HAVE_GROUP_MEMBER = @HAVE_GROUP_MEMBER@ +HAVE_INTTYPES_H = @HAVE_INTTYPES_H@ +HAVE_ISWBLANK = @HAVE_ISWBLANK@ +HAVE_ISWCNTRL = @HAVE_ISWCNTRL@ +HAVE_LANGINFO_ALTMON = @HAVE_LANGINFO_ALTMON@ +HAVE_LANGINFO_CODESET = @HAVE_LANGINFO_CODESET@ +HAVE_LANGINFO_ERA = @HAVE_LANGINFO_ERA@ +HAVE_LANGINFO_H = @HAVE_LANGINFO_H@ +HAVE_LANGINFO_T_FMT_AMPM = @HAVE_LANGINFO_T_FMT_AMPM@ +HAVE_LANGINFO_YESEXPR = @HAVE_LANGINFO_YESEXPR@ +HAVE_LCHOWN = @HAVE_LCHOWN@ +HAVE_LINK = @HAVE_LINK@ +HAVE_LINKAT = @HAVE_LINKAT@ +HAVE_LONG_LONG_INT = @HAVE_LONG_LONG_INT@ +HAVE_MAX_ALIGN_T = @HAVE_MAX_ALIGN_T@ +HAVE_MBRLEN = @HAVE_MBRLEN@ +HAVE_MBRTOWC = @HAVE_MBRTOWC@ +HAVE_MBSINIT = @HAVE_MBSINIT@ +HAVE_MBSLEN = @HAVE_MBSLEN@ +HAVE_MBSNRTOWCS = @HAVE_MBSNRTOWCS@ +HAVE_MBSRTOWCS = @HAVE_MBSRTOWCS@ +HAVE_MEMCHR = @HAVE_MEMCHR@ +HAVE_MEMPCPY = @HAVE_MEMPCPY@ +HAVE_MKDTEMP = @HAVE_MKDTEMP@ +HAVE_MKOSTEMP = @HAVE_MKOSTEMP@ +HAVE_MKOSTEMPS = @HAVE_MKOSTEMPS@ +HAVE_MKSTEMP = @HAVE_MKSTEMP@ +HAVE_MKSTEMPS = @HAVE_MKSTEMPS@ +HAVE_MSVC_INVALID_PARAMETER_HANDLER = @HAVE_MSVC_INVALID_PARAMETER_HANDLER@ +HAVE_NEWLOCALE = @HAVE_NEWLOCALE@ +HAVE_NL_LANGINFO = @HAVE_NL_LANGINFO@ +HAVE_OS_H = @HAVE_OS_H@ +HAVE_PCLOSE = @HAVE_PCLOSE@ +HAVE_PIPE = @HAVE_PIPE@ +HAVE_PIPE2 = @HAVE_PIPE2@ +HAVE_POPEN = @HAVE_POPEN@ +HAVE_POSIX_OPENPT = @HAVE_POSIX_OPENPT@ +HAVE_PREAD = @HAVE_PREAD@ +HAVE_PTSNAME = @HAVE_PTSNAME@ +HAVE_PTSNAME_R = @HAVE_PTSNAME_R@ +HAVE_PWRITE = @HAVE_PWRITE@ +HAVE_QSORT_R = @HAVE_QSORT_R@ +HAVE_RANDOM = @HAVE_RANDOM@ +HAVE_RANDOM_H = @HAVE_RANDOM_H@ +HAVE_RANDOM_R = @HAVE_RANDOM_R@ +HAVE_RAWMEMCHR = @HAVE_RAWMEMCHR@ +HAVE_READLINK = @HAVE_READLINK@ +HAVE_READLINKAT = @HAVE_READLINKAT@ +HAVE_REALLOCARRAY = @HAVE_REALLOCARRAY@ +HAVE_REALPATH = @HAVE_REALPATH@ +HAVE_RENAMEAT = @HAVE_RENAMEAT@ +HAVE_RPMATCH = @HAVE_RPMATCH@ +HAVE_SECURE_GETENV = @HAVE_SECURE_GETENV@ +HAVE_SETENV = @HAVE_SETENV@ +HAVE_SETHOSTNAME = @HAVE_SETHOSTNAME@ +HAVE_SIGNED_SIG_ATOMIC_T = @HAVE_SIGNED_SIG_ATOMIC_T@ +HAVE_SIGNED_WCHAR_T = @HAVE_SIGNED_WCHAR_T@ +HAVE_SIGNED_WINT_T = @HAVE_SIGNED_WINT_T@ +HAVE_SLEEP = @HAVE_SLEEP@ +HAVE_STDINT_H = @HAVE_STDINT_H@ +HAVE_STPCPY = @HAVE_STPCPY@ +HAVE_STPNCPY = @HAVE_STPNCPY@ +HAVE_STRCASECMP = @HAVE_STRCASECMP@ +HAVE_STRCASESTR = @HAVE_STRCASESTR@ +HAVE_STRCHRNUL = @HAVE_STRCHRNUL@ +HAVE_STRINGS_H = @HAVE_STRINGS_H@ +HAVE_STRPBRK = @HAVE_STRPBRK@ +HAVE_STRSEP = @HAVE_STRSEP@ +HAVE_STRTOD = @HAVE_STRTOD@ +HAVE_STRTOLL = @HAVE_STRTOLL@ +HAVE_STRTOULL = @HAVE_STRTOULL@ +HAVE_STRUCT_RANDOM_DATA = @HAVE_STRUCT_RANDOM_DATA@ +HAVE_STRVERSCMP = @HAVE_STRVERSCMP@ +HAVE_SYMLINK = @HAVE_SYMLINK@ +HAVE_SYMLINKAT = @HAVE_SYMLINKAT@ +HAVE_SYS_BITYPES_H = @HAVE_SYS_BITYPES_H@ +HAVE_SYS_CDEFS_H = @HAVE_SYS_CDEFS_H@ +HAVE_SYS_INTTYPES_H = @HAVE_SYS_INTTYPES_H@ +HAVE_SYS_LOADAVG_H = @HAVE_SYS_LOADAVG_H@ +HAVE_SYS_PARAM_H = @HAVE_SYS_PARAM_H@ +HAVE_SYS_TYPES_H = @HAVE_SYS_TYPES_H@ +HAVE_UNISTD_H = @HAVE_UNISTD_H@ +HAVE_UNLINKAT = @HAVE_UNLINKAT@ +HAVE_UNLOCKPT = @HAVE_UNLOCKPT@ +HAVE_UNSIGNED_LONG_LONG_INT = @HAVE_UNSIGNED_LONG_LONG_INT@ +HAVE_USLEEP = @HAVE_USLEEP@ +HAVE_VASPRINTF = @HAVE_VASPRINTF@ +HAVE_VDPRINTF = @HAVE_VDPRINTF@ +HAVE_WCHAR_H = @HAVE_WCHAR_H@ +HAVE_WCHAR_T = @HAVE_WCHAR_T@ +HAVE_WCPCPY = @HAVE_WCPCPY@ +HAVE_WCPNCPY = @HAVE_WCPNCPY@ +HAVE_WCRTOMB = @HAVE_WCRTOMB@ +HAVE_WCSCASECMP = @HAVE_WCSCASECMP@ +HAVE_WCSCAT = @HAVE_WCSCAT@ +HAVE_WCSCHR = @HAVE_WCSCHR@ +HAVE_WCSCMP = @HAVE_WCSCMP@ +HAVE_WCSCOLL = @HAVE_WCSCOLL@ +HAVE_WCSCPY = @HAVE_WCSCPY@ +HAVE_WCSCSPN = @HAVE_WCSCSPN@ +HAVE_WCSDUP = @HAVE_WCSDUP@ +HAVE_WCSFTIME = @HAVE_WCSFTIME@ +HAVE_WCSLEN = @HAVE_WCSLEN@ +HAVE_WCSNCASECMP = @HAVE_WCSNCASECMP@ +HAVE_WCSNCAT = @HAVE_WCSNCAT@ +HAVE_WCSNCMP = @HAVE_WCSNCMP@ +HAVE_WCSNCPY = @HAVE_WCSNCPY@ +HAVE_WCSNLEN = @HAVE_WCSNLEN@ +HAVE_WCSNRTOMBS = @HAVE_WCSNRTOMBS@ +HAVE_WCSPBRK = @HAVE_WCSPBRK@ +HAVE_WCSRCHR = @HAVE_WCSRCHR@ +HAVE_WCSRTOMBS = @HAVE_WCSRTOMBS@ +HAVE_WCSSPN = @HAVE_WCSSPN@ +HAVE_WCSSTR = @HAVE_WCSSTR@ +HAVE_WCSTOK = @HAVE_WCSTOK@ +HAVE_WCSWIDTH = @HAVE_WCSWIDTH@ +HAVE_WCSXFRM = @HAVE_WCSXFRM@ +HAVE_WCTRANS_T = @HAVE_WCTRANS_T@ +HAVE_WCTYPE_H = @HAVE_WCTYPE_H@ +HAVE_WCTYPE_T = @HAVE_WCTYPE_T@ +HAVE_WINSOCK2_H = @HAVE_WINSOCK2_H@ +HAVE_WINT_T = @HAVE_WINT_T@ +HAVE_WMEMCHR = @HAVE_WMEMCHR@ +HAVE_WMEMCMP = @HAVE_WMEMCMP@ +HAVE_WMEMCPY = @HAVE_WMEMCPY@ +HAVE_WMEMMOVE = @HAVE_WMEMMOVE@ +HAVE_WMEMSET = @HAVE_WMEMSET@ +HAVE_XLOCALE_H = @HAVE_XLOCALE_H@ +HAVE__BOOL = @HAVE__BOOL@ +HAVE__EXIT = @HAVE__EXIT@ +HELP2MAN = @HELP2MAN@ +INCLUDE_NEXT = @INCLUDE_NEXT@ +INCLUDE_NEXT_AS_FIRST_DIRECTIVE = @INCLUDE_NEXT_AS_FIRST_DIRECTIVE@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +INTLLIBS = @INTLLIBS@ +INTL_MACOSX_LIBS = @INTL_MACOSX_LIBS@ +LDFLAGS = @LDFLAGS@ +LIBGNU_LIBDEPS = @LIBGNU_LIBDEPS@ +LIBGNU_LTLIBDEPS = @LIBGNU_LTLIBDEPS@ +LIBICONV = @LIBICONV@ +LIBINTL = @LIBINTL@ +LIBMULTITHREAD = @LIBMULTITHREAD@ +LIBOBJS = @LIBOBJS@ +LIBPTH = @LIBPTH@ +LIBPTH_PREFIX = @LIBPTH_PREFIX@ +LIBS = @LIBS@ +LIBTHREAD = @LIBTHREAD@ +LIBUNISTRING_UNITYPES_H = @LIBUNISTRING_UNITYPES_H@ +LIBUNISTRING_UNIWIDTH_H = @LIBUNISTRING_UNIWIDTH_H@ +LIMITS_H = @LIMITS_H@ +LN_S = @LN_S@ +LOCALCHARSET_TESTS_ENVIRONMENT = @LOCALCHARSET_TESTS_ENVIRONMENT@ +LOCALE_FR = @LOCALE_FR@ +LOCALE_FR_UTF8 = @LOCALE_FR_UTF8@ +LOCALE_JA = @LOCALE_JA@ +LOCALE_ZH_CN = @LOCALE_ZH_CN@ +LTLIBICONV = @LTLIBICONV@ +LTLIBINTL = @LTLIBINTL@ +LTLIBMULTITHREAD = @LTLIBMULTITHREAD@ +LTLIBOBJS = @LTLIBOBJS@ +LTLIBPTH = @LTLIBPTH@ +LTLIBTHREAD = @LTLIBTHREAD@ + +# Use the programs built in our distribution, taking account of possible +# cross-compiling. +MAKEINFO = $(PERL) -I $(top_srcdir)/tp/ $(top_srcdir)/tp/texi2any.pl +MKDIR_P = @MKDIR_P@ +MKINSTALLDIRS = @MKINSTALLDIRS@ +MSGFMT = @MSGFMT@ +MSGFMT_015 = @MSGFMT_015@ +MSGMERGE = @MSGMERGE@ +NEXT_AS_FIRST_DIRECTIVE_ERRNO_H = @NEXT_AS_FIRST_DIRECTIVE_ERRNO_H@ +NEXT_AS_FIRST_DIRECTIVE_FLOAT_H = @NEXT_AS_FIRST_DIRECTIVE_FLOAT_H@ +NEXT_AS_FIRST_DIRECTIVE_GETOPT_H = @NEXT_AS_FIRST_DIRECTIVE_GETOPT_H@ +NEXT_AS_FIRST_DIRECTIVE_LANGINFO_H = @NEXT_AS_FIRST_DIRECTIVE_LANGINFO_H@ +NEXT_AS_FIRST_DIRECTIVE_LIMITS_H = @NEXT_AS_FIRST_DIRECTIVE_LIMITS_H@ +NEXT_AS_FIRST_DIRECTIVE_LOCALE_H = @NEXT_AS_FIRST_DIRECTIVE_LOCALE_H@ +NEXT_AS_FIRST_DIRECTIVE_STDARG_H = @NEXT_AS_FIRST_DIRECTIVE_STDARG_H@ +NEXT_AS_FIRST_DIRECTIVE_STDDEF_H = @NEXT_AS_FIRST_DIRECTIVE_STDDEF_H@ +NEXT_AS_FIRST_DIRECTIVE_STDINT_H = @NEXT_AS_FIRST_DIRECTIVE_STDINT_H@ +NEXT_AS_FIRST_DIRECTIVE_STDIO_H = @NEXT_AS_FIRST_DIRECTIVE_STDIO_H@ +NEXT_AS_FIRST_DIRECTIVE_STDLIB_H = @NEXT_AS_FIRST_DIRECTIVE_STDLIB_H@ +NEXT_AS_FIRST_DIRECTIVE_STRINGS_H = @NEXT_AS_FIRST_DIRECTIVE_STRINGS_H@ +NEXT_AS_FIRST_DIRECTIVE_STRING_H = @NEXT_AS_FIRST_DIRECTIVE_STRING_H@ +NEXT_AS_FIRST_DIRECTIVE_SYS_TYPES_H = @NEXT_AS_FIRST_DIRECTIVE_SYS_TYPES_H@ +NEXT_AS_FIRST_DIRECTIVE_UNISTD_H = @NEXT_AS_FIRST_DIRECTIVE_UNISTD_H@ +NEXT_AS_FIRST_DIRECTIVE_WCHAR_H = @NEXT_AS_FIRST_DIRECTIVE_WCHAR_H@ +NEXT_AS_FIRST_DIRECTIVE_WCTYPE_H = @NEXT_AS_FIRST_DIRECTIVE_WCTYPE_H@ +NEXT_ERRNO_H = @NEXT_ERRNO_H@ +NEXT_FLOAT_H = @NEXT_FLOAT_H@ +NEXT_GETOPT_H = @NEXT_GETOPT_H@ +NEXT_LANGINFO_H = @NEXT_LANGINFO_H@ +NEXT_LIMITS_H = @NEXT_LIMITS_H@ +NEXT_LOCALE_H = @NEXT_LOCALE_H@ +NEXT_STDARG_H = @NEXT_STDARG_H@ +NEXT_STDDEF_H = @NEXT_STDDEF_H@ +NEXT_STDINT_H = @NEXT_STDINT_H@ +NEXT_STDIO_H = @NEXT_STDIO_H@ +NEXT_STDLIB_H = @NEXT_STDLIB_H@ +NEXT_STRINGS_H = @NEXT_STRINGS_H@ +NEXT_STRING_H = @NEXT_STRING_H@ +NEXT_SYS_TYPES_H = @NEXT_SYS_TYPES_H@ +NEXT_UNISTD_H = @NEXT_UNISTD_H@ +NEXT_WCHAR_H = @NEXT_WCHAR_H@ +NEXT_WCTYPE_H = @NEXT_WCTYPE_H@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_DATE = @PACKAGE_DATE@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +PERL_EXT_CC = @PERL_EXT_CC@ +PERL_EXT_CFLAGS = @PERL_EXT_CFLAGS@ +PERL_EXT_CPPFLAGS = @PERL_EXT_CPPFLAGS@ +PERL_EXT_LDFLAGS = @PERL_EXT_LDFLAGS@ +POD2MAN = @POD2MAN@ +POSUB = @POSUB@ +PRAGMA_COLUMNS = @PRAGMA_COLUMNS@ +PRAGMA_SYSTEM_HEADER = @PRAGMA_SYSTEM_HEADER@ +PROVE = @PROVE@ +PTRDIFF_T_SUFFIX = @PTRDIFF_T_SUFFIX@ +RANLIB = @RANLIB@ +REPLACE_BTOWC = @REPLACE_BTOWC@ +REPLACE_CALLOC = @REPLACE_CALLOC@ +REPLACE_CANONICALIZE_FILE_NAME = @REPLACE_CANONICALIZE_FILE_NAME@ +REPLACE_CHOWN = @REPLACE_CHOWN@ +REPLACE_CLOSE = @REPLACE_CLOSE@ +REPLACE_DPRINTF = @REPLACE_DPRINTF@ +REPLACE_DUP = @REPLACE_DUP@ +REPLACE_DUP2 = @REPLACE_DUP2@ +REPLACE_DUPLOCALE = @REPLACE_DUPLOCALE@ +REPLACE_FACCESSAT = @REPLACE_FACCESSAT@ +REPLACE_FCHOWNAT = @REPLACE_FCHOWNAT@ +REPLACE_FCLOSE = @REPLACE_FCLOSE@ +REPLACE_FDOPEN = @REPLACE_FDOPEN@ +REPLACE_FFLUSH = @REPLACE_FFLUSH@ +REPLACE_FOPEN = @REPLACE_FOPEN@ +REPLACE_FPRINTF = @REPLACE_FPRINTF@ +REPLACE_FPURGE = @REPLACE_FPURGE@ +REPLACE_FREELOCALE = @REPLACE_FREELOCALE@ +REPLACE_FREOPEN = @REPLACE_FREOPEN@ +REPLACE_FSEEK = @REPLACE_FSEEK@ +REPLACE_FSEEKO = @REPLACE_FSEEKO@ +REPLACE_FTELL = @REPLACE_FTELL@ +REPLACE_FTELLO = @REPLACE_FTELLO@ +REPLACE_FTRUNCATE = @REPLACE_FTRUNCATE@ +REPLACE_GETCWD = @REPLACE_GETCWD@ +REPLACE_GETDELIM = @REPLACE_GETDELIM@ +REPLACE_GETDOMAINNAME = @REPLACE_GETDOMAINNAME@ +REPLACE_GETDTABLESIZE = @REPLACE_GETDTABLESIZE@ +REPLACE_GETGROUPS = @REPLACE_GETGROUPS@ +REPLACE_GETLINE = @REPLACE_GETLINE@ +REPLACE_GETLOGIN_R = @REPLACE_GETLOGIN_R@ +REPLACE_GETPAGESIZE = @REPLACE_GETPAGESIZE@ +REPLACE_GETPASS = @REPLACE_GETPASS@ +REPLACE_ISATTY = @REPLACE_ISATTY@ +REPLACE_ISWBLANK = @REPLACE_ISWBLANK@ +REPLACE_ISWCNTRL = @REPLACE_ISWCNTRL@ +REPLACE_ITOLD = @REPLACE_ITOLD@ +REPLACE_LCHOWN = @REPLACE_LCHOWN@ +REPLACE_LINK = @REPLACE_LINK@ +REPLACE_LINKAT = @REPLACE_LINKAT@ +REPLACE_LOCALECONV = @REPLACE_LOCALECONV@ +REPLACE_LSEEK = @REPLACE_LSEEK@ +REPLACE_MALLOC = @REPLACE_MALLOC@ +REPLACE_MBRLEN = @REPLACE_MBRLEN@ +REPLACE_MBRTOWC = @REPLACE_MBRTOWC@ +REPLACE_MBSINIT = @REPLACE_MBSINIT@ +REPLACE_MBSNRTOWCS = @REPLACE_MBSNRTOWCS@ +REPLACE_MBSRTOWCS = @REPLACE_MBSRTOWCS@ +REPLACE_MBSTATE_T = @REPLACE_MBSTATE_T@ +REPLACE_MBTOWC = @REPLACE_MBTOWC@ +REPLACE_MEMCHR = @REPLACE_MEMCHR@ +REPLACE_MEMMEM = @REPLACE_MEMMEM@ +REPLACE_MKSTEMP = @REPLACE_MKSTEMP@ +REPLACE_NEWLOCALE = @REPLACE_NEWLOCALE@ +REPLACE_NL_LANGINFO = @REPLACE_NL_LANGINFO@ +REPLACE_NULL = @REPLACE_NULL@ +REPLACE_OBSTACK_PRINTF = @REPLACE_OBSTACK_PRINTF@ +REPLACE_PERROR = @REPLACE_PERROR@ +REPLACE_POPEN = @REPLACE_POPEN@ +REPLACE_PREAD = @REPLACE_PREAD@ +REPLACE_PRINTF = @REPLACE_PRINTF@ +REPLACE_PTSNAME = @REPLACE_PTSNAME@ +REPLACE_PTSNAME_R = @REPLACE_PTSNAME_R@ +REPLACE_PUTENV = @REPLACE_PUTENV@ +REPLACE_PWRITE = @REPLACE_PWRITE@ +REPLACE_QSORT_R = @REPLACE_QSORT_R@ +REPLACE_RANDOM_R = @REPLACE_RANDOM_R@ +REPLACE_READ = @REPLACE_READ@ +REPLACE_READLINK = @REPLACE_READLINK@ +REPLACE_READLINKAT = @REPLACE_READLINKAT@ +REPLACE_REALLOC = @REPLACE_REALLOC@ +REPLACE_REALPATH = @REPLACE_REALPATH@ +REPLACE_REMOVE = @REPLACE_REMOVE@ +REPLACE_RENAME = @REPLACE_RENAME@ +REPLACE_RENAMEAT = @REPLACE_RENAMEAT@ +REPLACE_RMDIR = @REPLACE_RMDIR@ +REPLACE_SETENV = @REPLACE_SETENV@ +REPLACE_SETLOCALE = @REPLACE_SETLOCALE@ +REPLACE_SLEEP = @REPLACE_SLEEP@ +REPLACE_SNPRINTF = @REPLACE_SNPRINTF@ +REPLACE_SPRINTF = @REPLACE_SPRINTF@ +REPLACE_STDIO_READ_FUNCS = @REPLACE_STDIO_READ_FUNCS@ +REPLACE_STDIO_WRITE_FUNCS = @REPLACE_STDIO_WRITE_FUNCS@ +REPLACE_STPNCPY = @REPLACE_STPNCPY@ +REPLACE_STRCASESTR = @REPLACE_STRCASESTR@ +REPLACE_STRCHRNUL = @REPLACE_STRCHRNUL@ +REPLACE_STRDUP = @REPLACE_STRDUP@ +REPLACE_STRERROR = @REPLACE_STRERROR@ +REPLACE_STRERROR_R = @REPLACE_STRERROR_R@ +REPLACE_STRNCAT = @REPLACE_STRNCAT@ +REPLACE_STRNDUP = @REPLACE_STRNDUP@ +REPLACE_STRNLEN = @REPLACE_STRNLEN@ +REPLACE_STRSIGNAL = @REPLACE_STRSIGNAL@ +REPLACE_STRSTR = @REPLACE_STRSTR@ +REPLACE_STRTOD = @REPLACE_STRTOD@ +REPLACE_STRTOK_R = @REPLACE_STRTOK_R@ +REPLACE_STRUCT_LCONV = @REPLACE_STRUCT_LCONV@ +REPLACE_SYMLINK = @REPLACE_SYMLINK@ +REPLACE_SYMLINKAT = @REPLACE_SYMLINKAT@ +REPLACE_TMPFILE = @REPLACE_TMPFILE@ +REPLACE_TOWLOWER = @REPLACE_TOWLOWER@ +REPLACE_TRUNCATE = @REPLACE_TRUNCATE@ +REPLACE_TTYNAME_R = @REPLACE_TTYNAME_R@ +REPLACE_UNLINK = @REPLACE_UNLINK@ +REPLACE_UNLINKAT = @REPLACE_UNLINKAT@ +REPLACE_UNSETENV = @REPLACE_UNSETENV@ +REPLACE_USLEEP = @REPLACE_USLEEP@ +REPLACE_VASPRINTF = @REPLACE_VASPRINTF@ +REPLACE_VDPRINTF = @REPLACE_VDPRINTF@ +REPLACE_VFPRINTF = @REPLACE_VFPRINTF@ +REPLACE_VPRINTF = @REPLACE_VPRINTF@ +REPLACE_VSNPRINTF = @REPLACE_VSNPRINTF@ +REPLACE_VSPRINTF = @REPLACE_VSPRINTF@ +REPLACE_WCRTOMB = @REPLACE_WCRTOMB@ +REPLACE_WCSFTIME = @REPLACE_WCSFTIME@ +REPLACE_WCSNRTOMBS = @REPLACE_WCSNRTOMBS@ +REPLACE_WCSRTOMBS = @REPLACE_WCSRTOMBS@ +REPLACE_WCSWIDTH = @REPLACE_WCSWIDTH@ +REPLACE_WCTOB = @REPLACE_WCTOB@ +REPLACE_WCTOMB = @REPLACE_WCTOMB@ +REPLACE_WCWIDTH = @REPLACE_WCWIDTH@ +REPLACE_WRITE = @REPLACE_WRITE@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SIG_ATOMIC_T_SUFFIX = @SIG_ATOMIC_T_SUFFIX@ +SIZE_T_SUFFIX = @SIZE_T_SUFFIX@ +STDARG_H = @STDARG_H@ +STDBOOL_H = @STDBOOL_H@ +STDDEF_H = @STDDEF_H@ +STDINT_H = @STDINT_H@ +STRIP = @STRIP@ +TERMLIBS = @TERMLIBS@ +TEXINFO_DTD_VERSION = @TEXINFO_DTD_VERSION@ +UNDEFINE_STRTOK_R = @UNDEFINE_STRTOK_R@ +UNISTD_H_HAVE_WINSOCK2_H = @UNISTD_H_HAVE_WINSOCK2_H@ +UNISTD_H_HAVE_WINSOCK2_H_AND_USE_SOCKETS = @UNISTD_H_HAVE_WINSOCK2_H_AND_USE_SOCKETS@ +USE_EXTERNAL_EASTASIANWIDTH = @USE_EXTERNAL_EASTASIANWIDTH@ +USE_EXTERNAL_LIBINTL = @USE_EXTERNAL_LIBINTL@ +USE_EXTERNAL_UNIDECODE = @USE_EXTERNAL_UNIDECODE@ +USE_NLS = @USE_NLS@ +USE_UNICODE = @USE_UNICODE@ +VERSION = @VERSION@ +WCHAR_T_SUFFIX = @WCHAR_T_SUFFIX@ +WINDOWS_64_BIT_OFF_T = @WINDOWS_64_BIT_OFF_T@ +WINDOWS_STAT_INODES = @WINDOWS_STAT_INODES@ +WINT_T_SUFFIX = @WINT_T_SUFFIX@ +XGETTEXT = @XGETTEXT@ +XGETTEXT_015 = @XGETTEXT_015@ +XGETTEXT_EXTRA_OPTIONS = @XGETTEXT_EXTRA_OPTIONS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +enable_xs = @enable_xs@ +exec_prefix = @exec_prefix@ +gl_LIBOBJS = @gl_LIBOBJS@ +gl_LTLIBOBJS = @gl_LTLIBOBJS@ +gltests_LIBOBJS = @gltests_LIBOBJS@ +gltests_LTLIBOBJS = @gltests_LTLIBOBJS@ +gltests_WITNESS = @gltests_WITNESS@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +native_tools = @native_tools@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +@BUILD_PERL_API_TEXI_TRUE@dist_info_TEXINFOS = tp_api.texi +#info_TEXINFOS_SOURCES = tp_api.texi +@BUILD_PERL_API_TEXI_TRUE@tp_api_TEXINFOS = tp_api.texi +#dist_tp_api_TEXINFOS = tp_api.texi +#tp_api_SOURCES = tp_api.texi +@BUILD_PERL_API_TEXI_TRUE@BUILT_SOURCES = tp_api.texi + +#DISTCLEANFILES = tp_api.info +@BUILD_PERL_API_TEXI_TRUE@tp_api_dependencies = \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Common.pm $(top_srcdir)/tp/Texinfo/ParserNonXS.pm \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Structuring.pm $(top_srcdir)/tp/Texinfo/Report.pm \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Encoding.pm \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Convert/NodeNameNormalization.pm \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Convert/Text.pm \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Convert/Texinfo.pm \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Convert/Converter.pm \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Convert/Unicode.pm \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Convert/Info.pm \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Convert/DocBook.pm \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Convert/TexinfoXML.pm \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Convert/Plaintext.pm \ +@BUILD_PERL_API_TEXI_TRUE@ $(top_srcdir)/tp/Texinfo/Convert/HTML.pm + +@BUILD_PERL_API_TEXI_TRUE@EXTRA_DIST = api_includes tp_api.texi +all: $(BUILT_SOURCES) + $(MAKE) $(AM_MAKEFLAGS) all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/tp_api/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/tp_api/Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): +tags TAGS: + +ctags CTAGS: + +cscope cscopelist: + + +distdir: $(BUILT_SOURCES) + $(MAKE) $(AM_MAKEFLAGS) distdir-am + +distdir-am: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: $(BUILT_SOURCES) + $(MAKE) $(AM_MAKEFLAGS) check-am +all-am: Makefile +installdirs: +install: $(BUILT_SOURCES) + $(MAKE) $(AM_MAKEFLAGS) install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." + -test -z "$(BUILT_SOURCES)" || rm -f $(BUILT_SOURCES) +clean: clean-am + +clean-am: clean-generic mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: + +.MAKE: all check install install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic cscopelist-am \ + ctags-am distclean distclean-generic distdir dvi dvi-am html \ + html-am info info-am install install-am install-data \ + install-data-am install-dvi install-dvi-am install-exec \ + install-exec-am install-html install-html-am install-info \ + install-info-am install-man install-pdf install-pdf-am \ + install-ps install-ps-am install-strip installcheck \ + installcheck-am installdirs maintainer-clean \ + maintainer-clean-generic mostlyclean mostlyclean-generic pdf \ + pdf-am ps ps-am tags-am uninstall uninstall-am + +.PRECIOUS: Makefile + + +@BUILD_PERL_API_TEXI_TRUE@tp_api.texi: $(tp_api_dependencies) +@BUILD_PERL_API_TEXI_TRUE@ $(PERL) -I $(top_srcdir)/Pod-Simple-Texinfo/lib/ -I $(top_srcdir)/tp/ -I $(top_srcdir)/tp/maintain/lib/Text-Unidecode/lib/ -I $(top_srcdir)/tp/maintain/lib/libintl-perl/lib/ -I $(top_srcdir)/tp/maintain/lib/Unicode-EastAsianWidth/lib/ $(top_srcdir)/Pod-Simple-Texinfo/pod2texi.pl --base-level=section --top 'Texinfo perl module' --subdir=api_includes -o $@ $(tp_api_dependencies) + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Common.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Common.texi new file mode 100644 index 0000000000..aa97e56374 --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Common.texi @@ -0,0 +1,369 @@ +@node Texinfo::Common +@chapter Texinfo::Common + +@menu +* Texinfo@asis{::}Common NAME:: +* Texinfo@asis{::}Common SYNOPSIS:: +* Texinfo@asis{::}Common DESCRIPTION:: +* Texinfo@asis{::}Common COMMAND CLASSES:: +* Texinfo@asis{::}Common METHODS:: +* Texinfo@asis{::}Common SEE ALSO:: +* Texinfo@asis{::}Common AUTHOR:: +@end menu + +@node Texinfo::Common NAME +@section NAME + +Texinfo::Common - Classification of commands and miscellaneous methods + +@node Texinfo::Common SYNOPSIS +@section SYNOPSIS + +@verbatim + use Texinfo::Common qw(expand_today expand_verbatiminclude); + if ($Texinfo::Common::accent_commands{$a_command}) { + print STDERR "$a_command is an accent command\n"; + } + + my $today_tree = expand_today($converter); + my $verbatiminclude_tree + = expand_verbatiminclude(undef, $verbatiminclude); +@end verbatim + +@node Texinfo::Common DESCRIPTION +@section DESCRIPTION + +Texinfo::Common holds interesting hashes classifying Texinfo @@-commands, +as well as miscellaneous methods that may be useful for any backend +converting texinfo trees. + +It also defines, as our variable a hash for default indices, +named @code{%index_names}. The format of this hash is described in +@ref{Texinfo::Parser indices_information}. + +@node Texinfo::Common COMMAND CLASSES +@section COMMAND CLASSES + +Hashes are defined as @code{our} variables, and are therefore available +outside of the module. + +The key of the hashes are @@-command names without the @@. The +following hashes are available: + +@table @asis +@item %all_commands +@anchor{Texinfo::Common %all_commands} + +All the @@-commands. + +@item %no_brace_commands +@anchor{Texinfo::Common %no_brace_commands} + +Commands without brace with a single character as name, like @code{*} +or @code{:}. The value is an ascii representation of the command. It +may be an empty string. + +@item %misc_commands +@anchor{Texinfo::Common %misc_commands} + +Command that do not take braces and are not block commands either, like +@code{@@node}, @code{@@chapter}, @code{@@cindex}, @code{@@deffnx}, @code{@@end}, @code{@@footnotestyle}, +@code{@@set}, @code{@@settitle}, @code{@@indent}, @code{@@definfoenclose}, @code{@@comment} and many +others. + +@item %default_index_commands +@anchor{Texinfo::Common %default_index_commands} + +Index entry commands corresponding to default indices. For example +@code{@@cindex}. + +@item %root_commands +@anchor{Texinfo::Common %root_commands} + +Commands that are at the root of a Texinfo document, namely +@code{@@node} and sectioning commands, except heading commands. + +@item %sectioning_commands +@anchor{Texinfo::Common %sectioning_commands} + +All the sectioning and heading commands. + +@item %brace_commands +@anchor{Texinfo::Common %brace_commands} + +The commands that take braces. The associated value is the maximum +number of arguments. + +@item %letter_no_arg_commands +@anchor{Texinfo::Common %letter_no_arg_commands} + +@@-commands with braces but no argument corresponding to letters, +like @code{@@AA@{@}} or @code{@@ss@{@}} or @code{@@o@{@}}. + +@item %accent_commands +@anchor{Texinfo::Common %accent_commands} + +Accent @@-commands taking an argument, like @code{@@'} or @code{@@ringaccent} +including @code{@@dotless} and @code{@@tieaccent}. + +@item %style_commands +@anchor{Texinfo::Common %style_commands} + +Commands that mark a fragment of texinfo, like @code{@@strong}, +@code{@@cite}, @code{@@code} or @code{@@asis}. + +@item %code_style_commands +@anchor{Texinfo::Common %code_style_commands} + +@emph{style_commands} that have their argument in code style, like +@code{@@code}. + +@item %regular_font_style_commands +@anchor{Texinfo::Common %regular_font_style_commands} + +@emph{style_commands} that have their argument in regular font, like +@code{@@r} or @code{@@slanted}. + +@item %context_brace_commands +@anchor{Texinfo::Common %context_brace_commands} + +@@-commands with brace like @code{@@footnote}, @code{@@caption} and @code{@@math} +whose argument is outside of the main text flow in one way or another. + +@item %ref_commands +@anchor{Texinfo::Common %ref_commands} + +Cross reference @@-command referencing nodes, like @code{@@xref}. + +@item %explained_commands +@anchor{Texinfo::Common %explained_commands} + +@@-commands whose second argument explain first argument and further +@@-command call without first argument, as @code{@@abbr} and @code{@@acronym}. + +@item %block commands +@anchor{Texinfo::Common %block commands} + +Commands delimiting a block with a closing @code{@@end}. The value +is @emph{conditional} for @code{@@if} commands, @emph{def} for definition +commands like @code{@@deffn}, @emph{raw} for @@-commands that have no expansion +of @@-commands in their bodies and @emph{multitable} for @code{@@multitable}. +Otherwise it is set to the number of arguments separated by commas +that may appear on the @@-command line. That means 0 in most cases, +1 for @code{@@quotation} and 2 for @code{@@float}. + +@item %raw_commands +@anchor{Texinfo::Common %raw_commands} + +@@-commands that have no expansion of @@-commands in their bodies, +as @code{@@macro}, @code{@@verbatim} or @code{@@ignore}. + +@item %format_raw_commands +@anchor{Texinfo::Common %format_raw_commands} + +@@-commands associated with raw output format, like @code{@@html}, or +@code{@@docbook}. + +@item %texinfo_output_formats +@anchor{Texinfo::Common %texinfo_output_formats} + +Cannonical output formats that have associated conditionals. In +practice @code{%format_raw_commands} plus @code{info} and @code{plaintext}. + +@item %def_commands +@anchor{Texinfo::Common %def_commands} + +@item %def_aliases +@anchor{Texinfo::Common %def_aliases} + +Definition commands. @code{%def_aliases} associates an aliased command +to the original command, for example @code{defun} is associated to @code{deffn}. + +@item %menu_commands +@anchor{Texinfo::Common %menu_commands} + +@@-commands with menu entries. + +@item %align_commands +@anchor{Texinfo::Common %align_commands} + +@@-commands related with alignement of text. + +@item %region_commands +@anchor{Texinfo::Common %region_commands} + +Block @@-commands that enclose full text regions, like @code{@@titlepage}. + +@item %preformatted_commands +@anchor{Texinfo::Common %preformatted_commands} + +@item %preformatted_code_commands +@anchor{Texinfo::Common %preformatted_code_commands} + +@emph{%preformatted_commands} is for commands whose content should not +be filled, like @code{@@example} or @code{@@display}. If the command is meant +for code, it is also in @emph{%preformatted_code_commands}, like @code{@@example}. + +@item %item_container_commands +@anchor{Texinfo::Common %item_container_commands} + +Commands holding @code{@@item} with @code{@@item} that contains blocks of text, +like @code{@@itemize}. + +@item %item_line_commands +@anchor{Texinfo::Common %item_line_commands} + +Commands with @code{@@item} that have their arguments on their lines, like +@code{@@ftable}. + +@end table + +@node Texinfo::Common METHODS +@section METHODS + +No method is exported in the default case. + +Most methods takes a @emph{$converter} as argument, sometime optionally, +to get some information and use methods for error reporting, +see @ref{Texinfo::Convert::Converter NAME} and @ref{Texinfo::Report NAME}. + +@table @asis +@item $tree = expand_today($converter) +@anchor{Texinfo::Common $tree = expand_today($converter)} + +Expand today's date, as a texinfo tree with translations. + +@item $tree = expand_verbatiminclude($converter, $verbatiminclude) +@anchor{Texinfo::Common $tree = expand_verbatiminclude($converter@comma{} $verbatiminclude)} + +The @emph{$converter} argument may be undef. @emph{$verbatiminclude} is a +@code{@@verbatiminclude} tree element. This function returns a +@code{@@verbatim} tree elements after finding the included file and +reading it. If @emph{$converter} is not defined, the document encoding +is not taken into account when reading the file. + +@item $tree = definition_category($converter, $def_line) +@anchor{Texinfo::Common $tree = definition_category($converter@comma{} $def_line)} + +The @emph{$converter} argument may be undef. @emph{$def_line} is a +@code{def_line} texinfo tree container. This function +returns a texinfo tree corresponding to the category of the +@emph{$def_line} taking the class into account, if there is one. +If @emph{$converter} is not defined, the resulting string won't be +translated. + +@item $result = is_content_empty($tree, $do_not_ignore_index_entries) +@anchor{Texinfo::Common $result = is_content_empty($tree@comma{} $do_not_ignore_index_entries)} + +Return true if the @code{$tree} has content that could be formatted. +@code{$do_not_ignore_index_entries} is optional. If set, index entries +are considered to be formatted. + +@item $result = numbered_heading ($converter, $heading_element, $heading_text, $do_number) +@anchor{Texinfo::Common $result = numbered_heading ($converter@comma{} $heading_element@comma{} $heading_text@comma{} $do_number)} + +The @emph{$converter} argument may be undef. @emph{$heading_element} is +a heading command tree element. @emph{$heading_text} is the already +formatted heading text. if the @emph{$do_number} optional argument is +defined and false, no number is used and the text is returned as is. +This function returns the heading with a number and the appendix +part if needed. If @emph{$converter} is not defined, the resulting +string won't be translated. + +@item ($caption, $prepended) = float_name_caption ($converter, $float) +@anchor{Texinfo::Common ($caption@comma{} $prepended) = float_name_caption ($converter@comma{} $float)} + +@emph{$float} is a texinfo tree @code{@@float} element. This function +returns the caption that should be used for the float formatting +and the @emph{$prepended} texinfo tree combining the type and label +of the float. + +@item $text = enumerate_item_representation($specification, $number) +@anchor{Texinfo::Common $text = enumerate_item_representation($specification@comma{} $number)} + +This function returns the number or letter correponding to item +number @emph{$number} for an @code{@@enumerate} specification @emph{$specification}, +appearing on an @code{@@enumerate} line. For example + +@verbatim + enumerate_item_representation('c', 3) +@end verbatim + +is @code{e}. + +@item trim_spaces_comment_from_content($contents) +@anchor{Texinfo::Common trim_spaces_comment_from_content($contents)} + +Remove empty spaces after commands or braces at begin and +spaces and comments at end from a content array, modifying it. + +@item $normalized_name = normalize_top_node_name ($node_string) +@anchor{Texinfo::Common $normalized_name = normalize_top_node_name ($node_string)} + +Normalize the node name string given in argument, by normalizing +Top node case. + +@item protect_comma_in_tree($tree) +@anchor{Texinfo::Common protect_comma_in_tree($tree)} + +Protect comma characters, replacing @code{,} with @@comma@{@} in tree. + +@item protect_colon_in_tree($tree) +@anchor{Texinfo::Common protect_colon_in_tree($tree)} + +@item protect_node_after_label_in_tree($tree) +@anchor{Texinfo::Common protect_node_after_label_in_tree($tree)} + +Protect colon with @code{protect_colon_in_tree} and characters that +are special in node names after a label in menu entries (tab +dot and comma) with @code{protect_node_after_label_in_tree}. +The protection is achieved by putting protected characters +in @code{@@asis@{@}}. + +@item $contents_result = protect_first_parenthesis ($contents) +@anchor{Texinfo::Common $contents_result = protect_first_parenthesis ($contents)} + +Return a contents array reference with first parenthesis in the +contents array reference protected. + +@item protect_hashchar_at_line_beginning($parser, $tree) +@anchor{Texinfo::Common protect_hashchar_at_line_beginning($parser@comma{} $tree)} + +Protect hash character at beginning of line if the line is a cpp +line directive. The @emph{$parser} argument maybe undef, if it is +defined it is used for error reporting in case an hash character +could not be protected because it appeared in a raw environment. + +@item move_index_entries_after_items_in_tree($tree) +@anchor{Texinfo::Common move_index_entries_after_items_in_tree($tree)} + +In @code{@@enumerate} and @code{@@itemize} from the tree, move index entries +appearing just before @code{@@item} after the @code{@@item}. Comment lines +between index entries are moved too. + +@item $command = find_parent_root_command($parser, $tree_element) +@anchor{Texinfo::Common $command = find_parent_root_command($parser@comma{} $tree_element)} + +Find the parent root command of a tree element (sectioning command or node). +The @code{$parser} argument is optional, it is used to continue +through @code{@@insertcopying} if in a @code{@@copying}. + +@item valid_tree_transformation($name) +@anchor{Texinfo::Common valid_tree_transformation($name)} + +Return true if the @emph{$name} is a known tree transformation name +that may be passed with @code{TREE_TRANSFORMATIONS} to modify a texinfo +tree. + +@end table + +@node Texinfo::Common SEE ALSO +@section SEE ALSO + +@ref{Texinfo::Parser NAME}, @ref{Texinfo::Convert::Converter NAME} and @ref{Texinfo::Report NAME}. + +@node Texinfo::Common AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Converter.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Converter.texi new file mode 100644 index 0000000000..ca99e329cf --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Converter.texi @@ -0,0 +1,254 @@ +@node Texinfo::Convert::Converter +@chapter Texinfo::Convert::Converter + +@menu +* Texinfo@asis{::}Convert@asis{::}Converter NAME:: +* Texinfo@asis{::}Convert@asis{::}Converter SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Converter DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Converter METHODS:: +* Texinfo@asis{::}Convert@asis{::}Converter SEE ALSO:: +* Texinfo@asis{::}Convert@asis{::}Converter AUTHOR:: +* Texinfo@asis{::}Convert@asis{::}Converter POD ERRORS:: +@end menu + +@node Texinfo::Convert::Converter NAME +@section NAME + +Texinfo::Convert::Converter - Parent class for Texinfo tree converters + +@node Texinfo::Convert::Converter SYNOPSIS +@section SYNOPSIS + +@verbatim + package Texinfo::Convert::MyConverter; + + use Texinfo::Convert::Converter; + @ISA = qw(Texinfo::Convert::Converter); + + sub converter_defaults ($$) { + return %myconverter_defaults; + } + sub converter_initialize($) { + my $self = shift; + $self->{'document_context'} = [{}]; + } + sub converter_global_commands($) { + return ('documentlanguage', documentencoding', 'paragraphindent'); + } + + sub convert($$) { + ... + } + sub convert_tree($$) { + ... + } + sub output($$) { + ... + } + + # end of Texinfo::Convert::MyConverter + + my $converter = Texinfo::Convert::MyConverter->converter( + {'parser' => $parser}); + $converter->output($texinfo_tree); +@end verbatim + +@node Texinfo::Convert::Converter DESCRIPTION +@section DESCRIPTION + +Texinfo::Convert::Converter is a super class that can be used to +simplify converters initialization. The class also provide some +useful methods. + +In turn, the converter should define some methods. Three are +optional, @code{converter_defaults}, @code{converter_initialize} and +@code{converter_global_commands} and used for initialization, to +give @code{Texinfo::Convert::Converter} some informations. + +The @code{convert_tree} method is more or less mandatory and should +convert portions of Texinfo tree. The @code{output} and @code{convert} +are not required, but customarily used by converters as entry +points for conversion to a file with headers and so on, or +conversion of a whole Texinfo tree. + +Existing backends may be used as examples that implement those +methods. @code{Texinfo::Convert::Texinfo} together with +@code{Texinfo::Convert::PlainTexinfo}, as well as +@code{Texinfo::Convert::TextContent} are trivial examples. +@code{Texinfo::Convert::Text} is less trivial, although still simplistic, +while @code{Texinfo::Convert::DocBook} is a real converter +that is also not too complex. + +@ref{Texinfo::Common NAME}, @ref{Texinfo::Convert::Unicode NAME} +and @ref{Texinfo::Report NAME} document modules or additional function +that may be useful for backends, while the parsed Texinfo tree is +described in @ref{Texinfo::Parser NAME}. + +@node Texinfo::Convert::Converter METHODS +@section METHODS + +@menu +* Texinfo@asis{::}Convert@asis{::}Converter Initialization:: +* Texinfo@asis{::}Convert@asis{::}Converter Helper methods:: +@end menu + +@node Texinfo::Convert::Converter Initialization +@subsection Initialization + +A module subclassing @code{Texinfo::Convert::Converter} is created by calling +the @code{converter} method that should be inherited from +@code{Texinfo::Convert::Converter}. + +@table @asis +@item $converter = MyConverter->converter($options) +@anchor{Texinfo::Convert::Converter $converter = MyConverter->converter($options)} + +The @emph{$options} hash reference holds options for the converter. In +this option hash reference a @ref{Texinfo::Parser NAME, parser object, parser object} +may be associated with the @emph{parser} key. The other options +should be configuration options described in the Texinfo manual. +Those options, when appropriate, override the document content. + +The @code{converter} function returns a converter object (a blessed hash +reference) after checking the options and performing some initializations, +especially when a parser is given among the options. The converter is +also initialized as a @ref{Texinfo::Report NAME}. + +@end table + +To help with these initializations, the modules can define three methods: + +@table @asis +@item %defaults = $converter->converter_defaults($options) +@anchor{Texinfo::Convert::Converter %defaults = $converter->converter_defaults($options)} + +The converter can provide a defaults hash for configuration options. +The @emph{$options} hash reference holds options for the converter. + +@item @@global_commands = $converter->converter_global_commands() +@anchor{Texinfo::Convert::Converter @@global_commands = $converter->converter_global_commands()} + +The list returned is the list of Texinfo global commands (like +@code{@@paragraphindent}, @code{@@documentlanguage}...) that are relevant for the +converter. + +@item converter_initialize +@anchor{Texinfo::Convert::Converter converter_initialize} + +This method is called at the end of the converter initialization. + +@end table + +@node Texinfo::Convert::Converter Helper methods +@subsection Helper methods + +@code{Texinfo::Convert::Converter} provides methods +that may be useful for every converter: + +@table @asis +@item $converter->get_conf($option_string) +@anchor{Texinfo::Convert::Converter $converter->get_conf($option_string)} + +Returns the value of the Texinfo configuration option @emph{$option_string}. + +@item $converter->set_conf($option_string, $value) +@anchor{Texinfo::Convert::Converter $converter->set_conf($option_string@comma{} $value)} + +Set the Texinfo configuration option @emph{$option_string} to @emph{$value} if +not set as a converter option. + +@item $converter->force_conf($option_string, $value) +@anchor{Texinfo::Convert::Converter $converter->force_conf($option_string@comma{} $value)} + +Set the Texinfo configuration option @emph{$option_string} to @emph{$value}. +This should rarely be used, but the purpose of this method is to be able +to revert a configuration that is always wrong for a given output +format, like the splitting for example. + +@item $result = $converter->convert_document_sections($root, $file_handler) +@anchor{Texinfo::Convert::Converter $result = $converter->convert_document_sections($root@comma{} $file_handler)} + +This method splits the @emph{$root} Texinfo tree at sections and +calls @code{convert_tree} on the elements. If the optional @emph{$file_handler} +is given in argument, the result are output in @emph{$file_handler}, otherwise +the resulting string is returned. + +@item $result = $converter->convert_accents($accent_command, \&format_accents, $in_upper_case) +@anchor{Texinfo::Convert::Converter $result = $converter->convert_accents($accent_command@comma{} \&format_accents@comma{} $in_upper_case)} + +@emph{$accent_command} is an accent command, which may have other accent +commands nested. The function returns the accents formatted either +as encoded letters, or formatted using @emph{\&format_accents}. +If @emph{$in_upper_case} is set, the result should be uppercased. + +@end table + +Other @code{Texinfo::Convert::Converter} methods target conversion to XML: + +@table @asis +@item $protected_text = $converter->xml_protect_text($text) +@anchor{Texinfo::Convert::Converter $protected_text = $converter->xml_protect_text($text)} + +Protect special XML characters (&, <, >, ") of @emph{$text}. + +@item $comment = $converter->xml_comment($text) +@anchor{Texinfo::Convert::Converter $comment = $converter->xml_comment($text)} + +Returns an XML comment for @emph{$text}. + +@item $result = xml_accent($text, $accent_command, $in_upper_case, $use_numeric_entities) +@anchor{Texinfo::Convert::Converter $result = xml_accent($text@comma{} $accent_command@comma{} $in_upper_case@comma{} $use_numeric_entities)} + +@emph{$text} is the text appearing within an accent command. @emph{$accent_command} +should be a Texinfo tree element corresponding to an accent command taking +an argument. @emph{$in_upper_case} is optional, and, if set, the text is put +in upper case. The function returns the accented letter as XML entity +if possible. @emph{$use_numeric_entities} is also optional, and, if set, and +there is no XML entity, the numerical entity corresponding to Unicode +points is preferred to an ASCII transliteration. + +@item $result = $converter->xml_accents($accent_command, $in_upper_case) +@anchor{Texinfo::Convert::Converter $result = $converter->xml_accents($accent_command@comma{} $in_upper_case)} + +@emph{$accent_command} is an accent command, which may have other accent +commands nested. If @emph{$in_upper_case} is set, the result should be +upper cased. The function returns the accents formatted as XML. + +@end table + +Finally, there is: + +@table @asis +@item $result = $converter->output_internal_links() +@anchor{Texinfo::Convert::Converter $result = $converter->output_internal_links()} + +At this level, the method just returns undef. It is used in the HTML +output, following the @code{--internal-links} option of texi2any/makeinfo +specification. + +@end table + +@node Texinfo::Convert::Converter SEE ALSO +@section SEE ALSO + +@ref{Texinfo::Common NAME}, @ref{Texinfo::Convert::Unicode NAME}, @ref{Texinfo::Report NAME} +and @ref{Texinfo::Parser NAME}. + +@node Texinfo::Convert::Converter AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + +@node Texinfo::Convert::Converter POD ERRORS +@section POD ERRORS + +Hey! @strong{The above document had some coding errors, which are explained below:} + +@table @asis +@item Around line 1760: +@anchor{Texinfo::Convert::Converter Around line 1760:} + +'=item' outside of any '=over' + +@end table + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-DocBook.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-DocBook.texi new file mode 100644 index 0000000000..89d63fefcb --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-DocBook.texi @@ -0,0 +1,76 @@ +@node Texinfo::Convert::DocBook +@chapter Texinfo::Convert::DocBook + +@menu +* Texinfo@asis{::}Convert@asis{::}DocBook NAME:: +* Texinfo@asis{::}Convert@asis{::}DocBook SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}DocBook DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}DocBook METHODS:: +* Texinfo@asis{::}Convert@asis{::}DocBook AUTHOR:: +@end menu + +@node Texinfo::Convert::DocBook NAME +@section NAME + +Texinfo::Convert::DocBook - Convert Texinfo tree to DocBook + +@node Texinfo::Convert::DocBook SYNOPSIS +@section SYNOPSIS + +@verbatim + my $converter + = Texinfo::Convert::DocBook->converter({'parser' => $parser}); + + $converter->output($tree); + $converter->convert($tree); + $converter->convert_tree($tree); +@end verbatim + +@node Texinfo::Convert::DocBook DESCRIPTION +@section DESCRIPTION + +Texinfo::Convert::DocBook converts a Texinfo tree to DocBook. + +@node Texinfo::Convert::DocBook METHODS +@section METHODS + +@table @asis +@item $converter = Texinfo::Convert::DocBook->converter($options) +@anchor{Texinfo::Convert::DocBook $converter = Texinfo::Convert::DocBook->converter($options)} + +Initialize converter from Texinfo to DocBook. + +The @emph{$options} hash reference holds options for the converter. In +this option hash reference a parser object may be associated with the +@emph{parser} key. The other options should be configuration options +described in the Texinfo manual. Those options, when appropriate, +override the document content. + +See @ref{Texinfo::Convert::Converter NAME} for more informations. + +@item $converter->output($tree) +@anchor{Texinfo::Convert::DocBook $converter->output($tree)} + +Convert a Texinfo tree @emph{$tree} and output the result in files as +described in the Texinfo manual. + +@item $result = $converter->convert($tree) +@anchor{Texinfo::Convert::DocBook $result = $converter->convert($tree)} + +Convert a Texinfo tree @emph{$tree} or tree portion and return +the resulting output. + +@item $result = $converter->convert_tree($tree) +@anchor{Texinfo::Convert::DocBook $result = $converter->convert_tree($tree)} + +Convert a Texinfo tree portion @emph{$tree} and return the resulting +output. This function does not try to output a full document but only +portions. For a full document use @code{convert}. + +@end table + +@node Texinfo::Convert::DocBook AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-HTML.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-HTML.texi new file mode 100644 index 0000000000..0ec39b33f6 --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-HTML.texi @@ -0,0 +1,84 @@ +@node Texinfo::Convert::HTML +@chapter Texinfo::Convert::HTML + +@menu +* Texinfo@asis{::}Convert@asis{::}HTML NAME:: +* Texinfo@asis{::}Convert@asis{::}HTML SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}HTML DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}HTML METHODS:: +* Texinfo@asis{::}Convert@asis{::}HTML AUTHOR:: +@end menu + +@node Texinfo::Convert::HTML NAME +@section NAME + +Texinfo::Convert::HTML - Convert Texinfo tree to HTML + +@node Texinfo::Convert::HTML SYNOPSIS +@section SYNOPSIS + +@verbatim + my $converter + = Texinfo::Convert::HTML->converter({'parser' => $parser}); + + $converter->output($tree); + $converter->convert($tree); + $converter->convert_tree($tree); + $converter->output_internal_links(); # HTML only +@end verbatim + +@node Texinfo::Convert::HTML DESCRIPTION +@section DESCRIPTION + +Texinfo::Convert::HTML converts a Texinfo tree to HTML. + +@node Texinfo::Convert::HTML METHODS +@section METHODS + +@table @asis +@item $converter = Texinfo::Convert::HTML->converter($options) +@anchor{Texinfo::Convert::HTML $converter = Texinfo::Convert::HTML->converter($options)} + +Initialize converter from Texinfo to HTML. + +The @emph{$options} hash reference holds options for the converter. In +this option hash reference a parser object may be associated with the +@emph{parser} key. The other options should be configuration options +described in the Texinfo manual. Those options, when appropriate, +override the document content. + +See @ref{Texinfo::Convert::Converter NAME} for more informations. + +@item $converter->output($tree) +@anchor{Texinfo::Convert::HTML $converter->output($tree)} + +Convert a Texinfo tree @emph{$tree} and output the result in files as +described in the Texinfo manual. + +@item $result = $converter->convert($tree) +@anchor{Texinfo::Convert::HTML $result = $converter->convert($tree)} + +Convert a Texinfo tree @emph{$tree} or tree portion and return +the resulting output. + +@item $result = $converter->convert_tree($tree) +@anchor{Texinfo::Convert::HTML $result = $converter->convert_tree($tree)} + +Convert a Texinfo tree portion @emph{$tree} and return the resulting +output. This function does not try to output a full document but only +portions. For a full document use @code{convert}. + +@item $result = $converter->output_internal_links() +@anchor{Texinfo::Convert::HTML $result = $converter->output_internal_links()} + +Returns text representing the links in the document. The format should +follow the @code{--internal-links} option of the texi2any/makeinfo +specification. This is only supported in (and relevant for) HTML. + +@end table + +@node Texinfo::Convert::HTML AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Info.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Info.texi new file mode 100644 index 0000000000..6a78de235d --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Info.texi @@ -0,0 +1,76 @@ +@node Texinfo::Convert::Info +@chapter Texinfo::Convert::Info + +@menu +* Texinfo@asis{::}Convert@asis{::}Info NAME:: +* Texinfo@asis{::}Convert@asis{::}Info SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Info DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Info METHODS:: +* Texinfo@asis{::}Convert@asis{::}Info AUTHOR:: +@end menu + +@node Texinfo::Convert::Info NAME +@section NAME + +Texinfo::Convert::Info - Convert Texinfo tree to Info + +@node Texinfo::Convert::Info SYNOPSIS +@section SYNOPSIS + +@verbatim + my $converter + = Texinfo::Convert::Info->converter({'parser' => $parser}); + + $converter->output($tree); + $converter->convert($tree); + $converter->convert_tree($tree); +@end verbatim + +@node Texinfo::Convert::Info DESCRIPTION +@section DESCRIPTION + +Texinfo::Convert::Info converts a Texinfo tree to Info. + +@node Texinfo::Convert::Info METHODS +@section METHODS + +@table @asis +@item $converter = Texinfo::Convert::Info->converter($options) +@anchor{Texinfo::Convert::Info $converter = Texinfo::Convert::Info->converter($options)} + +Initialize converter from Texinfo to Info. + +The @emph{$options} hash reference holds options for the converter. In +this option hash reference a parser object may be associated with the +@emph{parser} key. The other options should be configuration options +described in the Texinfo manual. Those options, when appropriate, +override the document content. + +See @ref{Texinfo::Convert::Converter NAME} for more informations. + +@item $converter->output($tree) +@anchor{Texinfo::Convert::Info $converter->output($tree)} + +Convert a Texinfo tree @emph{$tree} and output the result in files as +described in the Texinfo manual. + +@item $result = $converter->convert($tree) +@anchor{Texinfo::Convert::Info $result = $converter->convert($tree)} + +Convert a Texinfo tree @emph{$tree} or tree portion and return +the resulting output. + +@item $result = $converter->convert_tree($tree) +@anchor{Texinfo::Convert::Info $result = $converter->convert_tree($tree)} + +Convert a Texinfo tree portion @emph{$tree} and return the resulting +output. This function does not try to output a full document but only +portions. For a full document use @code{convert}. + +@end table + +@node Texinfo::Convert::Info AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-NodeNameNormalization.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-NodeNameNormalization.texi new file mode 100644 index 0000000000..c36fa2c5de --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-NodeNameNormalization.texi @@ -0,0 +1,73 @@ +@node Texinfo::Convert::NodeNameNormalization +@chapter Texinfo::Convert::NodeNameNormalization + +@menu +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization NAME:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization METHODS:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization AUTHOR:: +@end menu + +@node Texinfo::Convert::NodeNameNormalization NAME +@section NAME + +Texinfo::Convert::NodeNameNormalization - Normalize and transliterate Texinfo trees + +@node Texinfo::Convert::NodeNameNormalization SYNOPSIS +@section SYNOPSIS + +@verbatim + use Texinfo::Convert::NodeNameNormalization qw(normalize_node + transliterate_texinfo); + + my $normalized = normalize_node({'contents' => $node_contents}); + + my $file_name = transliterate_texinfo({'contents' + => $section_contents}); +@end verbatim + +@node Texinfo::Convert::NodeNameNormalization DESCRIPTION +@section DESCRIPTION + +Texinfo::Convert::NodeNameNormalization allows to normalize node names, +with @code{normalize_node} following the specification described in the +Texinfo manual for HTML Xref. This is usefull each time one want a +unique identifier for Texinfo content that is only composed of letter, +digits, @code{-} and @code{_}. In @code{Texinfo::Parser} @code{normalize_node} is used +for node, floats and anchor names normalization, but also float +types @code{@@acronym} and @code{@@abbr} first argument. + +It is also possible to transliterate non ascii letters, instead of mangling +them, with @code{transliterate_texinfo}, losing the uniqueness feature of +normalized node names. + +@node Texinfo::Convert::NodeNameNormalization METHODS +@section METHODS + +@table @asis +@item $normalized = normalize_node($tree) +@anchor{Texinfo::Convert::NodeNameNormalization $normalized = normalize_node($tree)} + +The Texinfo @emph{$tree} is returned as a string, normalized as described in the +Texinfo manual for HTML Xref. + +The result will be poor for Texinfo trees which are not @@-command arguments +(on an @@-command line or in braces), for instance if the tree contains +@code{@@node} or block commands. + +@item $transliterated = transliterate_texinfo($tree, $no_unidecode) +@anchor{Texinfo::Convert::NodeNameNormalization $transliterated = transliterate_texinfo($tree@comma{} $no_unidecode)} + +The Texinfo @emph{$tree} is returned as a string, with non ascii letters +transliterated as ascii, but otherwise similar with @code{normalize_node} +output. If the optional @emph{$no_unidecode} argument is set, @code{Text::Unidecode} +is not used for characters whose transliteration is not built-in. + +@end table + +@node Texinfo::Convert::NodeNameNormalization AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Plaintext.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Plaintext.texi new file mode 100644 index 0000000000..26a45ca2b8 --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Plaintext.texi @@ -0,0 +1,76 @@ +@node Texinfo::Convert::Plaintext +@chapter Texinfo::Convert::Plaintext + +@menu +* Texinfo@asis{::}Convert@asis{::}Plaintext NAME:: +* Texinfo@asis{::}Convert@asis{::}Plaintext SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Plaintext DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Plaintext METHODS:: +* Texinfo@asis{::}Convert@asis{::}Plaintext AUTHOR:: +@end menu + +@node Texinfo::Convert::Plaintext NAME +@section NAME + +Texinfo::Convert::Plaintext - Convert Texinfo tree to Plaintext + +@node Texinfo::Convert::Plaintext SYNOPSIS +@section SYNOPSIS + +@verbatim + my $converter + = Texinfo::Convert::Plaintext->converter({'parser' => $parser}); + + $converter->output($tree); + $converter->convert($tree); + $converter->convert_tree($tree); +@end verbatim + +@node Texinfo::Convert::Plaintext DESCRIPTION +@section DESCRIPTION + +Texinfo::Convert::Plaintext converts a Texinfo tree to Plaintext. + +@node Texinfo::Convert::Plaintext METHODS +@section METHODS + +@table @asis +@item $converter = Texinfo::Convert::Plaintext->converter($options) +@anchor{Texinfo::Convert::Plaintext $converter = Texinfo::Convert::Plaintext->converter($options)} + +Initialize converter from Texinfo to Plaintext. + +The @emph{$options} hash reference holds options for the converter. In +this option hash reference a parser object may be associated with the +@emph{parser} key. The other options should be configuration options +described in the Texinfo manual. Those options, when appropriate, +override the document content. + +See @ref{Texinfo::Convert::Converter NAME} for more informations. + +@item $converter->output($tree) +@anchor{Texinfo::Convert::Plaintext $converter->output($tree)} + +Convert a Texinfo tree @emph{$tree} and output the result in files as +described in the Texinfo manual. + +@item $result = $converter->convert($tree) +@anchor{Texinfo::Convert::Plaintext $result = $converter->convert($tree)} + +Convert a Texinfo tree @emph{$tree} or tree portion and return +the resulting output. + +@item $result = $converter->convert_tree($tree) +@anchor{Texinfo::Convert::Plaintext $result = $converter->convert_tree($tree)} + +Convert a Texinfo tree portion @emph{$tree} and return the resulting +output. This function does not try to output a full document but only +portions. For a full document use @code{convert}. + +@end table + +@node Texinfo::Convert::Plaintext AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Texinfo.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Texinfo.texi new file mode 100644 index 0000000000..0fcf8a06d3 --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Texinfo.texi @@ -0,0 +1,50 @@ +@node Texinfo::Convert::Texinfo +@chapter Texinfo::Convert::Texinfo + +@menu +* Texinfo@asis{::}Convert@asis{::}Texinfo NAME:: +* Texinfo@asis{::}Convert@asis{::}Texinfo SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Texinfo DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Texinfo METHODS:: +* Texinfo@asis{::}Convert@asis{::}Texinfo AUTHOR:: +@end menu + +@node Texinfo::Convert::Texinfo NAME +@section NAME + +Texinfo::Convert::Texinfo - Convert a Texinfo tree to Texinfo code + +@node Texinfo::Convert::Texinfo SYNOPSIS +@section SYNOPSIS + +@verbatim + use Texinfo::Convert::Texinfo qw(convert); + + my $texinfo_text = convert($tree); +@end verbatim + +@node Texinfo::Convert::Texinfo DESCRIPTION +@section DESCRIPTION + +Texinfo::Convert::Texinfo converts a Texinfo tree (described in +@ref{Texinfo::Parser NAME}) to Texinfo code. If the Texinfo tree results from +parsing some Texinfo document, The converted Texinfo code should be +exactly the same as the initial document, except that user defined @@-macros +and @code{@@value} are expanded, and some invalid code is discarded. + +@node Texinfo::Convert::Texinfo METHODS +@section METHODS + +@table @asis +@item $texinfo_text = convert($tree) +@anchor{Texinfo::Convert::Texinfo $texinfo_text = convert($tree)} + +Converts the Texinfo tree @emph{$tree} to Texinfo code. + +@end table + +@node Texinfo::Convert::Texinfo AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-TexinfoXML.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-TexinfoXML.texi new file mode 100644 index 0000000000..3b9229b10c --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-TexinfoXML.texi @@ -0,0 +1,76 @@ +@node Texinfo::Convert::TexinfoXML +@chapter Texinfo::Convert::TexinfoXML + +@menu +* Texinfo@asis{::}Convert@asis{::}TexinfoXML NAME:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML METHODS:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML AUTHOR:: +@end menu + +@node Texinfo::Convert::TexinfoXML NAME +@section NAME + +Texinfo::Convert::TexinfoXML - Convert Texinfo tree to TexinfoXML + +@node Texinfo::Convert::TexinfoXML SYNOPSIS +@section SYNOPSIS + +@verbatim + my $converter + = Texinfo::Convert::TexinfoXML->converter({'parser' => $parser}); + + $converter->output($tree); + $converter->convert($tree); + $converter->convert_tree($tree); +@end verbatim + +@node Texinfo::Convert::TexinfoXML DESCRIPTION +@section DESCRIPTION + +Texinfo::Convert::TexinfoXML converts a Texinfo tree to TexinfoXML. + +@node Texinfo::Convert::TexinfoXML METHODS +@section METHODS + +@table @asis +@item $converter = Texinfo::Convert::TexinfoXML->converter($options) +@anchor{Texinfo::Convert::TexinfoXML $converter = Texinfo::Convert::TexinfoXML->converter($options)} + +Initialize converter from Texinfo to TexinfoXML. + +The @emph{$options} hash reference holds options for the converter. In +this option hash reference a parser object may be associated with the +@emph{parser} key. The other options should be configuration options +described in the Texinfo manual. Those options, when appropriate, +override the document content. + +See @ref{Texinfo::Convert::Converter NAME} for more informations. + +@item $converter->output($tree) +@anchor{Texinfo::Convert::TexinfoXML $converter->output($tree)} + +Convert a Texinfo tree @emph{$tree} and output the result in files as +described in the Texinfo manual. + +@item $result = $converter->convert($tree) +@anchor{Texinfo::Convert::TexinfoXML $result = $converter->convert($tree)} + +Convert a Texinfo tree @emph{$tree} or tree portion and return +the resulting output. + +@item $result = $converter->convert_tree($tree) +@anchor{Texinfo::Convert::TexinfoXML $result = $converter->convert_tree($tree)} + +Convert a Texinfo tree portion @emph{$tree} and return the resulting +output. This function does not try to output a full document but only +portions. For a full document use @code{convert}. + +@end table + +@node Texinfo::Convert::TexinfoXML AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Text.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Text.texi new file mode 100644 index 0000000000..595cbf916e --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Text.texi @@ -0,0 +1,140 @@ +@node Texinfo::Convert::Text +@chapter Texinfo::Convert::Text + +@menu +* Texinfo@asis{::}Convert@asis{::}Text NAME:: +* Texinfo@asis{::}Convert@asis{::}Text SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Text DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Text METHODS:: +* Texinfo@asis{::}Convert@asis{::}Text AUTHOR:: +@end menu + +@node Texinfo::Convert::Text NAME +@section NAME + +Texinfo::Convert::Text - Convert Texinfo tree to simple text + +@node Texinfo::Convert::Text SYNOPSIS +@section SYNOPSIS + +@verbatim + use Texinfo::Convert::Text qw(convert ascii_accent text_accents); + + my $result = convert($tree); + my $result_encoded = convert($tree, + {'enabled_encoding' => 'utf-8'}); + my $result_converter = convert($tree, + {'converter' => $converter}); + + my $result_accent_text = ascii_accent('e', $accent_command); + my $accents_text = text_accents($accents, 'utf-8'); +@end verbatim + +@node Texinfo::Convert::Text DESCRIPTION +@section DESCRIPTION + +Texinfo::Convert::Text is a simple backend that converts a Texinfo tree +to simple text. It is used for some command argument expansion in +@code{Texinfo::Parser}, for instance the file names, or encoding names. +The converter is very simple, and, in the default case, cannot handle +output strings translation or error handling. + +@node Texinfo::Convert::Text METHODS +@section METHODS + +@table @asis +@item $result = convert($tree, $options) +@anchor{Texinfo::Convert::Text $result = convert($tree@comma{} $options)} + +Convert a Texinfo tree to simple text. @emph{$options} is a hash reference of +options. The converter is very simple, and has no internal state besides +the options. It cannot handle as is output strings translation or error +storing. + +If the @emph{converter} option is set, some additional features may be available +for the conversion of some @@-commands, like output strings translation or +error reporting. + +The following options may be set: + +@table @asis +@item enabled_encoding +@anchor{Texinfo::Convert::Text enabled_encoding} + +If set, the value is considered to be the encoding name texinfo accented +letters should be converted to. This option corresponds to the +@code{--enable-encoding} option, or the @code{ENABLE_ENCODING} customization +variable. + +@item sc +@anchor{Texinfo::Convert::Text sc} + +If set, the text is upper-cased. + +@item code +@anchor{Texinfo::Convert::Text code} + +If set the text is in code style. (mostly --, ---, '' and `` are kept as +is). + +@item NUMBER_SECTIONS +@anchor{Texinfo::Convert::Text NUMBER_SECTIONS} + +If set, sections are numbered when output. + +@item sort_string +@anchor{Texinfo::Convert::Text sort_string} + +A somehow internal option to convert to text more suitable for alphabetical +sorting rather than presentation. + +@item converter +@anchor{Texinfo::Convert::Text converter} + +If this converter object is passed to the function, some features of this +object may be used during conversion. Mostly error reporting and strings +translation, as the converter object is also supposed to be a +@ref{Texinfo::Report NAME} objet. See also @ref{Texinfo::Convert::Converter NAME}. + +@item expanded_formats_hash +@anchor{Texinfo::Convert::Text expanded_formats_hash} + +A reference on a hash. The keys should be format names (like @code{html}, +@code{tex}), and if thecorresponding value is set, the format is expanded. + +@end table + +@item $result_accent_text = ascii_accent($text, $accent_command) +@anchor{Texinfo::Convert::Text $result_accent_text = ascii_accent($text@comma{} $accent_command)} + +@emph{$text} is the text appearing within an accent command. @emph{$accent_command} +should be a Texinfo tree element corresponding to an accent command taking +an argument. The function returns a transliteration of the accented +character. + +@item $result_accent_text = ascii_accent_fallback($converter, $text, $accent_command) +@anchor{Texinfo::Convert::Text $result_accent_text = ascii_accent_fallback($converter@comma{} $text@comma{} $accent_command)} + +Same as @code{ascii_accent} but with an additional first argument +converter, which is in ignored, but needed if this function is to +be in argument of functions that need a fallback for accents +conversion. + +@item $accents_text = text_accents($accents, $encoding, $set_case) +@anchor{Texinfo::Convert::Text $accents_text = text_accents($accents@comma{} $encoding@comma{} $set_case)} + +@emph{$accents} is an accent command that may contain other nested accent +commands. The function will format the whole stack of nested accent +commands and the innermost text. If @emph{$encoding} is set, the formatted +text is converted to this encoding as much as possible instead of being +converted as simple ascii. If @emph{$set_case} is positive, the result +is meant to be upper-cased, if it is negative, the result is to be +lower-cased. + +@end table + +@node Texinfo::Convert::Text AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Unicode.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Unicode.texi new file mode 100644 index 0000000000..232f316274 --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Convert-Unicode.texi @@ -0,0 +1,103 @@ +@node Texinfo::Convert::Unicode +@chapter Texinfo::Convert::Unicode + +@menu +* Texinfo@asis{::}Convert@asis{::}Unicode NAME:: +* Texinfo@asis{::}Convert@asis{::}Unicode SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Unicode DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Unicode METHODS:: +* Texinfo@asis{::}Convert@asis{::}Unicode AUTHOR:: +@end menu + +@node Texinfo::Convert::Unicode NAME +@section NAME + +Texinfo::Convert::Unicode - Handle conversion to Unicode + +@node Texinfo::Convert::Unicode SYNOPSIS +@section SYNOPSIS + +@verbatim + use Texinfo::Convert::Unicode qw(unicode_accent encoded_accents + unicode_text); + + my ($innermost_contents, $stack) + = Texinfo::Common::find_innermost_accent_contents($accent); + + my $formatted_accents = encoded_accents ($converter, + convert($innermost_contents), $stack, $encoding, + \&Texinfo::Text::ascii_accent_fallback); + + my $accent_text = unicode_accent('e', $accent_command); +@end verbatim + +@node Texinfo::Convert::Unicode DESCRIPTION +@section DESCRIPTION + +Texinfo::Convert::Unicode provides methods that deals with unicode for +converters. Unicode is important, because it is used internally in perl +for strings, therefore if converted to Unicode, a string could be output +in other encodings as well when writting out the converted documents. + +When an encoding is given as argument of a method of the module, the +accented letters should only be converted to unicode if it is known that +it will be possible to convert the unicode points to encoded charactes +in the encoding character set. + +@node Texinfo::Convert::Unicode METHODS +@section METHODS + +@table @asis +@item $result = unicode_accent($text, $accent_command) +@anchor{Texinfo::Convert::Unicode $result = unicode_accent($text@comma{} $accent_command)} + +@emph{$text} is the text appearing within an accent command. @emph{$accent_command} +should be a Texinfo tree element corresponding to an accent command taking +an argument. The function returns the unicode representation of the accented +character. + +@item $result = encoded_accents ($converter, $text, $stack, $encoding, $format_accent, $set_case) +@anchor{Texinfo::Convert::Unicode $result = encoded_accents ($converter@comma{} $text@comma{} $stack@comma{} $encoding@comma{} $format_accent@comma{} $set_case)} + +@emph{$converter} is a converter object. It may be undef if there is no need of +converter object in @emph{$format_accent} (@emph{$format_accent} described below). +@emph{$text} is the text appearing within nested accent commands. @emph{$stack} is +an array reference holding the nested accents texinfo element trees. For +example, @emph{$text} could be the formatted content and @emph{$stack} the stack +returned by @code{Texinfo::Common::find_innermost_accent_contents}. @emph{$encoding} +is the encoding the accented characters should be encoded to. If +@emph{$encoding} not set the @emph{$result} is set to undef. @emph{$format_accent} +is a function reference that is used to format the accent commands if +there is no encoded character available for the encoding @emph{$encoding} +at some point of the conversion of the @emph{$stack}. Last, if +@emph{$set_case} is positive, the result is upper-cased, while if it is negative, +the result is lower-cased. + +@item $result = unicode_text ($text, $in_code) +@anchor{Texinfo::Convert::Unicode $result = unicode_text ($text@comma{} $in_code)} + +Return @emph{$text} with characters encoded in unicode. If @emph{$in_code} +is set, the text is considered to be in code style. + +@item $result = unicode_for_brace_no_arg_command($command_name, $encoding) +@anchor{Texinfo::Convert::Unicode $result = unicode_for_brace_no_arg_command($command_name@comma{} $encoding)} + +Return the unicode representing a command with brace and no argument +@emph{$command_name} (like @code{@@bullet@{@}}, @code{@@aa@{@}} or @code{@@guilsinglleft@{@}}), +or undef if there is no available encoded character for encoding +@emph{$encoding}. + +@item $width = string_width($string) +@anchor{Texinfo::Convert::Unicode $width = string_width($string)} + +Return the string width, taking into account the fact that some characters +have a zero width (like composing accents) while some have a width of 2 +(most chinese characters, for example). + +@end table + +@node Texinfo::Convert::Unicode AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Encoding.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Encoding.texi new file mode 100644 index 0000000000..627b93ab65 --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Encoding.texi @@ -0,0 +1,51 @@ +@node Texinfo::Encoding +@chapter Texinfo::Encoding + +@menu +* Texinfo@asis{::}Encoding NAME:: +* Texinfo@asis{::}Encoding SYNOPSIS:: +* Texinfo@asis{::}Encoding DESCRIPTION:: +* Texinfo@asis{::}Encoding METHODS:: +* Texinfo@asis{::}Encoding AUTHOR:: +@end menu + +@node Texinfo::Encoding NAME +@section NAME + +Texinfo::Encoding - Encodings and encoding aliases + +@node Texinfo::Encoding SYNOPSIS +@section SYNOPSIS + +@verbatim + use Texinfo::Encoding qw(encoding_alias); + + my ($canonical_texinfo_encoding, $perl_encoding, + $canonical_output_encoding) = encoding_alias($encoding); +@end verbatim + +@node Texinfo::Encoding DESCRIPTION +@section DESCRIPTION + +Texinfo::Encoding takes care of encoding definition and aliasing. + +@node Texinfo::Encoding METHODS +@section METHODS + +@table @asis +@item ($canonical_texinfo_encoding, $perl_encoding, $canonical_output_encoding) = encoding_alias($encoding) +@anchor{Texinfo::Encoding ($canonical_texinfo_encoding@comma{} $perl_encoding@comma{} $canonical_output_encoding) = encoding_alias($encoding)} + +Taking an encoding name as argument, the function returns the +corresponding canonical Texinfo encoding @emph{$canonical_texinfo_encoding} +as described in the Texinfo manual (or undef), an encoding name suitable +for perl @emph{$perl_encoding}, and an encoding name suitable for most +output formaats, especially HTML, @emph{$canonical_output_encoding}. + +@end table + +@node Texinfo::Encoding AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Parser.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Parser.texi new file mode 100644 index 0000000000..26fadf340c --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Parser.texi @@ -0,0 +1,1428 @@ +@node Texinfo::Parser +@chapter Texinfo::Parser + +@menu +* Texinfo@asis{::}Parser NAME:: +* Texinfo@asis{::}Parser SYNOPSIS:: +* Texinfo@asis{::}Parser DESCRIPTION:: +* Texinfo@asis{::}Parser METHODS:: +* Texinfo@asis{::}Parser TEXINFO TREE:: +* Texinfo@asis{::}Parser SEE ALSO:: +* Texinfo@asis{::}Parser AUTHOR:: +@end menu + +@node Texinfo::Parser NAME +@section NAME + +Texinfo::Parser - Parse Texinfo code into a Perl tree + +@node Texinfo::Parser SYNOPSIS +@section SYNOPSIS + +@verbatim + use Texinfo::Parser; + my $parser = Texinfo::Parser::parser(); + my $tree = $parser->parse_texi_file("somefile.texi"); + my ($errors, $errors_count) = $parser->errors(); + foreach my $error_message (@$errors) { + warn $error_message->{'error_line'}; + } + + my $index_names = $parser->indices_information(); + my $float_types_arrays = $parser->floats_information(); + my $internal_references_array + = $parser->internal_references_information(); + # An hash reference on normalized node/float/anchor names + my $labels_information = $parser->labels_information(); + # A hash reference, keys are @-command names, value is an + # array reference holding all the corresponding @-commands. + my $global_commands_information = $parser->global_commands_information(); + # a hash reference on some document informations (encodings, + # input file name, dircategory and direntry list, for exampel). + my $global_informations = $parser->global_informations(); +@end verbatim + +@node Texinfo::Parser DESCRIPTION +@section DESCRIPTION + +Texinfo::Parser will parse Texinfo text into a perl tree. In one pass +it expands user-defined @@-commands, conditionals (@@ifset, @@ifinfo...) +and @@value and constructs the tree. Some extra information is gathered +while doing the tree: for example, the block command associated with @@end, +the number of rows in a multitable, or the node associated with a section. + +@node Texinfo::Parser METHODS +@section METHODS + +No method is exported in the default case. The module allows both +an object-oriented syntax, or traditional function, with the parser +as an opaque data structure given as an argument to every function. + +@menu +* Texinfo@asis{::}Parser Initialization:: +* Texinfo@asis{::}Parser Parsing Texinfo text:: +* Texinfo@asis{::}Parser Getting information on the document:: +* Texinfo@asis{::}Parser Texinfo Parser options:: +@end menu + +@node Texinfo::Parser Initialization +@subsection Initialization + +The following method is used to construct a new @code{Texinfo::Parser} object: + +@table @asis +@item $parser = Texinfo::Parser::parser($options); +@anchor{Texinfo::Parser $parser = Texinfo::Parser::parser($options);} + +This method creates a new parser. The options may be provided as a hash +reference. There are two types of option. The first type of option +change the way the parser behaves; they are described right here. The +other type of option allows giving the parser some information as if +it came from texinfo code; for example, allow setting aliases (as with +@code{@@alias}), values (as with @code{@@set}), or merged indices (as with +@code{@@synindex}). These options are described below in @ref{Texinfo::Parser Texinfo Parser options,, Texinfo Parser options}. + +@table @asis +@item expanded_formats +@anchor{Texinfo::Parser expanded_formats} + +An array reference of the output formats for which @code{@@if@emph{FORMAT}} +conditional blocks should be expanded. Default is empty. + +@item include_directories +@anchor{Texinfo::Parser include_directories} + +An array reference of directories in which @code{@@include} files should be +searched for. Default contains the working directory, @file{.}. + +@item IGNORE_BEFORE_SETFILENAME +@anchor{Texinfo::Parser IGNORE_BEFORE_SETFILENAME} + +If set, and @code{@@setfilename} exists, everything before @code{@@setfilename} +is put in a special container type, @@@code{preamble_before_setfilename}. +This option is set in the default case. + +@item IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME +@anchor{Texinfo::Parser IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME} + +If set, spaces after an @@-command name that take braces are ignored. +Default on. + +@item MAX_MACRO_CALL_NESTING +@anchor{Texinfo::Parser MAX_MACRO_CALL_NESTING} + +Maximal number of nested user-defined macro calls. Default is 100000. + +@item SHOW_MENU +@anchor{Texinfo::Parser SHOW_MENU} + +If false, no menu-related errors are reported. Default is true. + +@end table + +@end table + +@node Texinfo::Parser Parsing Texinfo text +@subsection Parsing Texinfo text + +There are three methods that may be called to parse some Texinfo code: +@code{parse_texi_line} for a line, @code{parse_texi_text} for a text fragment, +and @code{parse_texi_file} for a file. + +For all those functions, if the @emph{$parser} argument is undef, a new +parser object is generated to parse the line. Otherwise the parser given +as an argument is used to parse into a tree. + +When @code{parse_texi_text} is used, the resulting tree is rooted at +a @code{root_line} type container. Otherwise, the resulting tree should be +rooted at a @code{text_root} type container if it does not contain nodes or +sections, at a @code{document_root} type container otherwise. + +@table @asis +@item $tree = parse_texi_line($parser, $text, $first_line_number, $file_name, $macro_name, $fixed_line_number) +@anchor{Texinfo::Parser $tree = parse_texi_line($parser@comma{} $text@comma{} $first_line_number@comma{} $file_name@comma{} $macro_name@comma{} $fixed_line_number)} + +This function is used to parse a short fragment of Texinfo code. + +@emph{$text} may be either an array reference of lines, or a text. + +The other arguments are optional and allow specifying the position +information of the Texinfo code. @emph{$first_line_number} is the line number +of the first text line. @emph{$file_name} is the name of the file the +text comes from. @emph{$macro} is for the user-defined macro name the text +is expanded from. If @emph{$fixed_line_number} is set, the line number is +not increased for the different lines, as if the text was the expansion +of a macro. + +@item $tree = parse_texi_text ($parser, $text, $line_numbers_specification, $file_name, $macro_name, $fixed_line_number) +@anchor{Texinfo::Parser $tree = parse_texi_text ($parser@comma{} $text@comma{} $line_numbers_specification@comma{} $file_name@comma{} $macro_name@comma{} $fixed_line_number)} + +This function is used to parse some Texinfo text. + +@emph{$text} may be either an array reference of lines, or a text. + +The other arguments are optional and allow specifying the position +information of the Texinfo code. There are two distinct cases for +@emph{$line_numbers_specification}. + +@enumerate +@item If it is an array reference, it is considered to hold objects describing +the position information of each text line. + +@item If @emph{$line_numbers_specification} is a scalar, it is the line number of +the first text line. In that case (like for @code{parse_texi_text}), +@emph{$file_name} is the name of the file the text comes from. +and @emph{$macro} is for the user-defined macro name the text +is expanded from. If @emph{$fixed_line_number} is set, the line number is +not increased for the different lines, as if the text was the expansion +of a macro. + +@end enumerate + +@item $tree = parse_texi_file($parser, $file_name) +@anchor{Texinfo::Parser $tree = parse_texi_file($parser@comma{} $file_name)} + +The file with name @emph{$file_name} is considered to be a Texinfo file and +is parsed into a tree. + +undef is returned if the file couldn't be read. + +@end table + +The errors collected during the tree parsing are available through the +@code{errors} method. This method comes from @code{Texinfo::Report}, and is +described in @ref{Texinfo::Report ($error_warnings_list@comma{} $error_count) = errors ($converter), errors, errors}. + +@node Texinfo::Parser Getting information on the document +@subsection Getting information on the document + +After parsing some information about the Texinfo code that was processed +is available from the parser. + +Some global information is available through @code{global_informations} + +@table @asis +@item $info = global_informations($parser) +@anchor{Texinfo::Parser $info = global_informations($parser)} + +The @emph{$info} returned is a hash reference. The possible keys are + +@table @asis +@item input_file_name +@anchor{Texinfo::Parser input_file_name} + +The name of the main Texinfo input file. + +@item input_encoding_name +@anchor{Texinfo::Parser input_encoding_name} + +@item input_perl_encoding +@anchor{Texinfo::Parser input_perl_encoding} + +@code{input_encoding_name} string is the encoding name used for the +Texinfo code. +@code{input_perl_encoding} string is a corresponding perl encoding name. + +@item dircategory_direntry +@anchor{Texinfo::Parser dircategory_direntry} + +An array of successive @code{@@dircategory} and @code{@@direntry} as they appear +in the document. + +@item novalidate +@anchor{Texinfo::Parser novalidate} + +If set, it is as if @code{@@novalidate} was set in the document. + +@end table + +@end table + +Some command lists are available, such that it is possible to go through +the corresponding tree elements without walking the tree. They are +available through @code{global_commands_information} + +@table @asis +@item $commands = global_commands_information($parser) +@anchor{Texinfo::Parser $commands = global_commands_information($parser)} + +@emph{$commands} is an hash reference. The keys are @@-command names. The +associated values are array references containing all the corresponding +tree elements. + +@end table + +All the @@-commands that have an associated label (so can be the +target of cross references) - @code{@@node}, @code{@@anchor} and @code{@@float} with +label - have a normalized name associated, constructed as described in the +@strong{HTML Xref} node in the Texinfo manual. Those normalized labels and +the association with @@-commands is available through @code{labels_information}: + +@table @asis +@item $labels_information = labels_information($parser) +@anchor{Texinfo::Parser $labels_information = labels_information($parser)} + +@emph{$labels_information} is a hash reference whose keys are normalized +labels, and the associated value is the corresponding @@-command. + +@end table + +Information on @code{@@float} is also available, grouped by type of +floats, each type correponding to potential @code{@@listoffloats}. +This information is available through the method @code{floats_information}. + +@table @asis +@item $float_types = floats_information($parser) +@anchor{Texinfo::Parser $float_types = floats_information($parser)} + +@emph{$float_types} is a hash reference whose keys are normalized float +types (the first float argument, or the @code{@@listoffloats} argument). +The normalization is the same as for node names. The value is the list +of float tree elements appearing in the texinfo document. + +@end table + +Internal references, that is, @@-commands that refer to node, anchors +or floats within the document are also available: + +@table @asis +@item $internal_references_array = internal_references_information($parser); +@anchor{Texinfo::Parser $internal_references_array = internal_references_information($parser);} + +The function returns a list of cross-reference commands referring to +the same document. + +@end table + +Information about defined indices, merged indices and index entries is +also available through the @code{indices_information} method. + +@table @asis +@item indices_information +@anchor{Texinfo::Parser indices_information} + +@verbatim + $index_names = indices_information($parser); +@end verbatim + +The index names is a hash reference. The keys are + +@table @asis +@item in_code +@anchor{Texinfo::Parser in_code} + +1 if the index entries should be formatted as code, 0 in the opposite case. + +@item name +@anchor{Texinfo::Parser name} + +The index name. + +@item prefix +@anchor{Texinfo::Parser prefix} + +An array reference of prefix associated to the index. + +@item merged_in +@anchor{Texinfo::Parser merged_in} + +In case the index is merged to another index, this key holds the name of +the index the index is merged into. It takes into account indirectly +merged indices. + +@item contained_indices +@anchor{Texinfo::Parser contained_indices} + +An hash reference holding names of indices that are merged into the index, +including itself. It also contains indirectly merged indices. This key +is removed if the index is itself later merged to another index. + +@item index_entries +@anchor{Texinfo::Parser index_entries} + +An array reference containing index entry structures for index entries +associated with the index. The index entry could be associated to +@@-commands like @code{@@cindex}, or @code{@@item} in @code{@@vtable}, or definition +commands entries like @code{@@deffn}. + +The keys of the index entry structures are + +@table @asis +@item index_name +@anchor{Texinfo::Parser index_name} + +The index name. + +@item index_at_command +@anchor{Texinfo::Parser index_at_command} + +The name of the @@-command associated with the index entry. + +@item index_type_command +@anchor{Texinfo::Parser index_type_command} + +The @@-command associated with the index entry allowing to +find the index type. + +@item content +@anchor{Texinfo::Parser content} + +An array reference corresponding to the index entry content. + +@item content_normalized +@anchor{Texinfo::Parser content_normalized} + +An array reference corresponding to the index entry content, independent +of the current language. + +@item command +@anchor{Texinfo::Parser command} + +The element in the parsed tree associated with the @@-command holding the +index entry. + +@item node +@anchor{Texinfo::Parser node} + +The node in the parsed tree containing the index entry. + +@item number +@anchor{Texinfo::Parser number} + +The number of the index entry. + +@item region +@anchor{Texinfo::Parser region} + +The region command (@code{@@copying}, @code{@@titlepage}) containing the index entry, +if it is in such an environement. + +@end table + +@end table + +The following shows the references corresponding to the default indexes +@emph{cp} and @emph{fn}, the @emph{fn} index having its entries formatted as code and +the indices corresponding to the following texinfo + +@verbatim + @defindex some + @defcodeindex code + + $index_names = {'cp' => {'name' => 'cp', 'in_code' => 0, }, + 'fn' => {'name' => 'fn', 'in_code' => 1, }, + 'some' => {'in_code' => 0}, + 'code' => {'in_code' => 1}}; +@end verbatim + +If @code{name} is not set, it is set to the index name. + +@end table + +@node Texinfo::Parser Texinfo Parser options +@subsection Texinfo Parser options + +Setting these options is the same as seeing some Texinfo constructs in the +document. + +@table @asis +@item aliases +@anchor{Texinfo::Parser aliases} + +A hash reference. The key is a command name, the value is the alias, as +could be set by @code{@@alias}. + +@item clickstyle +@anchor{Texinfo::Parser clickstyle} + +A string, the command name associated with @code{@@clickstyle}. + +@item documentlanguage +@anchor{Texinfo::Parser documentlanguage} + +A string corresponding to a document language set by @code{@@documentlanguage}. + +@item INPUT_ENCODING_NAME +@anchor{Texinfo::Parser INPUT_ENCODING_NAME} + +@item INPUT_PERL_ENCODING +@anchor{Texinfo::Parser INPUT_PERL_ENCODING} + +@code{INPUT_ENCODING_NAME} string is the encoding name as set +by @code{@@documentencoding}. +@code{INPUT_PERL_ENCODING} string is a corresponding perl encoding name. +In general those two strings should be set simultaneously. + +@item indices +@anchor{Texinfo::Parser indices} + +If it is a hash reference, the keys are index names, the values are +index prefix hash references. The index prefix hash reference values are +prefix, the value is set if the corresponding index entries should be +formatted as if in @code{@@code}. An example is as @ref{Texinfo::Parser indices_information,, indices_information}. + +If it is an array reference, it is a list of index names, as if they were +entered as + +@verbatim + @defindex name +@end verbatim + +@item kbdinputstyle +@anchor{Texinfo::Parser kbdinputstyle} + +A string, the @code{@@kbdinputstyle} style. + +@item labels +@anchor{Texinfo::Parser labels} + +A hash reference. Keys are normalized node names as described in the +@strong{HTML Xref} node in the Texinfo manual. Instead of a node, it may also +be a float label or an anchor name. The value is the corresponding +@@-command element in the tree. + +@item macros +@anchor{Texinfo::Parser macros} + +The associated hash reference has as keys user-defined macro names. The +value is the reference on a macro definition element as obtained by +the Parser when parsing a @code{@@macro}. For example + +@verbatim + @macro mymacro{arg} + coucou \arg\ after arg + @end macro +@end verbatim + +Is associated to a macro definition element + +@verbatim + {'cmdname' => 'macro', + 'args' => [{'text' => 'mymacro', 'type' => 'macro_name'}, + {'text' => 'arg', 'type' => 'macro_arg}], + 'contents' => [{'text' => "coucou \arg\ after arg\n", 'type' => 'raw'}], + 'extra' => {'arg_line' => " mymacro{arg}\n", }} +@end verbatim + += item merged_indices + +The associated hash reference holds merged indices information, each key +is merged in the value. Same as setting @code{@@synindex} or @code{syncodeindex}. + +@item sections_level +@anchor{Texinfo::Parser sections_level} + +Modifier of the sections level. Same as calling @code{@@lowersections} or +@code{@@raisesections}. + +@item values +@anchor{Texinfo::Parser values} + +A hash reference. Keys are names, values are the corresponding values. +Same as values set by @code{@@set}. + +@end table + +@node Texinfo::Parser TEXINFO TREE +@section TEXINFO TREE + +A Texinfo tree element (called element because node is overloaded in +the Texinfo world) is an hash reference. There are three main categories +of tree element. Tree elements associated with an @@-command have a +@code{cmdname} key holding the @@-command name. Tree elements corresponding +to text fragments have a @code{text} key holding the corresponding text. +Finally, the last category is other containers (hereafter called +containers) which in most cases have a @code{type} key holding their name. +Text fragments and @@-command elements may also have an associated type +when such information is needed. + +The children of an @@-command or container element are in the array +referred to with the @code{args} key or with the @code{contents} key. The +@code{args} key is for arguments of @@-commands, either in braces or on +the rest of the line after the command, depending on the type of command. +@code{args} is also used for the elements of a menu entry, as a menu +entry is well-structured with a limited number of arguments. +The @code{contents} key array holds the contents of the texinfo +code appearing within a block @@-command, within a container, +or within a @code{@@node} or sectioning @@-command. + +Another important key for the elements is the @code{extra} key which is +associated to a hash reference and holds all kinds of information that +is gathered during the parsing and may help with the conversion. + +You can see examples of the tree structure by running makeinfo like +this: + +@verbatim + makeinfo -c DUMP_TREE=1 -c TEXINFO_OUTPUT_FORMAT=parse document.texi +@end verbatim + +For a simpler, more regular representation of the tree structure, you +can do: + +@verbatim + makeinfo -c TEXINFO_OUTPUT_FORMAT=debugtree document.texi +@end verbatim + +@menu +* Texinfo@asis{::}Parser Element keys:: +* Texinfo@asis{::}Parser Element types:: +* Texinfo@asis{::}Parser Information available in the extra key:: +* Texinfo@asis{::}Parser Other information set by the parser:: +@end menu + +@node Texinfo::Parser Element keys +@subsection Element keys + +@table @asis +@item cmdname +@anchor{Texinfo::Parser cmdname} + +The command name of @@-command elements. + +@item text +@anchor{Texinfo::Parser text} + +The text fragment of text elements. + +@item type +@anchor{Texinfo::Parser type} + +The type of the element. For @code{@@verb} it is the delimiter. But otherwise +it is the type of element considered as a container. Frequent types +encountered are @emph{paragraph} for a paragraph container, +@emph{brace_command_arg} for the container holding the brace @@-commands +contents, @emph{line_arg} and @emph{block_line_arg} contain the arguments +appearing on the line of @@-commands. Text fragments may have a type to +give an information of the kind of text fragment, for example +@code{empty_spaces_before_argument} is associated to spaces after a brace +opening and before the argument. Many @@-commands elements don't have +a type associated. + +@item args +@anchor{Texinfo::Parser args} + +Arguments in braces or on @@-command line, and the elements of a menu entry. + +@item contents +@anchor{Texinfo::Parser contents} + +The Texinfo appearing in the element. For block commands, other +containers, @code{@@node} and sectioning commands. + +@item parent +@anchor{Texinfo::Parser parent} + +The parent element. + +@item line_nr +@anchor{Texinfo::Parser line_nr} + +An hash reference corresponding to information on the location of the +element in the Texinfo input manual. It should only be available for +@@-command elements, and only for @@-commands that are considered to be +complex enough that the location in the document is needed, for example +to prepare an error message. + +The keys of the line number hash references are + +@table @asis +@item line_nr +@anchor{Texinfo::Parser line_nr 1} + +The line number of the @@-command. + +@item file_name +@anchor{Texinfo::Parser file_name} + +The file name where @@-command appeared. + +@item macro +@anchor{Texinfo::Parser macro} + +The user macro name the @@-command is expanded from. + +@end table + +@item extra +@anchor{Texinfo::Parser extra} + +A hash reference holding any additional information. +See @ref{Texinfo::Parser Information available in the extra key,, Information available in the extra key}. + +@end table + +@node Texinfo::Parser Element types +@subsection Element types + +@menu +* Texinfo@asis{::}Parser Types for command elements:: +* Texinfo@asis{::}Parser Types for text elements:: +* Texinfo@asis{::}Parser Types of container elements:: +@end menu + +@node Texinfo::Parser Types for command elements +@subsubsection Types for command elements + +Some types can be associated with @@-commands (in addition to the element +being described by @code{cmdname}), although usually there will be no type +at all. As said above, for @code{@@verb} the type is the delimiter. For a +@code{@@value} command that is not expanded because there is no corresponding +value set, the type is the value argument string. + +The following are the other possible values of @code{type} for tree elements +for @@-commands. + +@table @asis +@item def_line +@anchor{Texinfo::Parser def_line} + +This type may be associated with a definition command with a x form, +like @code{@@defunx}, @code{@@defvrx}. For the form without x, the associated +@emph{def_line} is the first @code{contents} element. It is described in more +details below. + +@item command_as_argument +@anchor{Texinfo::Parser command_as_argument} + +This is the type of a command given in argument of @code{@@itemize}, +@code{@@table}, @code{@@vtable} or @code{@@ftable}. For example in + +@verbatim + @itemize @bullet + @item item + @end itemize +@end verbatim + +the element corresponding with bullet has the following keys: + +@verbatim + 'cmdname' => 'bullet' + 'type' => 'command_as_argument' +@end verbatim + +The parent @@-command has an entry in extra for the @emph{command_as_argument} +element: + +@verbatim + 'cmdname' => 'itemize' + 'extra => {'command_as_argument' => $command_element_as_argument} +@end verbatim + +@item index_entry_command +@anchor{Texinfo::Parser index_entry_command} + +This is the type of index entry command like @code{@@cindex}, and, more +importantly user-defined index entry commands. So for example if there +is + +@verbatim + @defindex foo + ... + + @fooindex index entry +@end verbatim + +the @code{@@fooindex} @@-command element will have the @emph{index_entry_command} +type. + +@item following_arg +@anchor{Texinfo::Parser following_arg} + +This type is set for non-alphabetic accent @@-commands that don't use braces +but instead have their argument right after them, as + +@verbatim + @~n +@end verbatim + +@item space_command_arg +@anchor{Texinfo::Parser space_command_arg} + +This type is set for accent @@-commands that don't use brace but instead +have their argument after some space, as + +@verbatim + @ringaccent A +@end verbatim + +@item definfoenclose_command +@anchor{Texinfo::Parser definfoenclose_command} + +This type is set for an @@-command that is redefined by @code{@@definfoenclose}. +The beginning is in @code{@{'extra'@}->@{'begin'@}} and the end in +@code{@{'extra'@}->@{'end'@}}. + +@end table + +@node Texinfo::Parser Types for text elements +@subsubsection Types for text elements + +The text elements may have the following types (or may have no type +at all): + +@table @asis +@item empty_line +@anchor{Texinfo::Parser empty_line} + +An empty line (possibly containing whitespace characters only). + +@item empty_line_after_command +@anchor{Texinfo::Parser empty_line_after_command} + +@item empty_spaces_after_command +@anchor{Texinfo::Parser empty_spaces_after_command} + +The text is spaces for @emph{empty_spaces_after_command} +or spaces followed by a newline for +@emph{empty_line_after_command}, appearing after an @@-command that +takes an argument on the line or a block @@-command. + +@item empty_spaces_before_argument +@anchor{Texinfo::Parser empty_spaces_before_argument} + +The text is spaces appearing after an opening brace or after a +comma separating a command's arguments. + +@item spaces_at_end +@anchor{Texinfo::Parser spaces_at_end} + +Space at the end of an argument to a line command, at the end of an +comma-separated argument for some brace commands, or at the end of +bracketed content on a @code{@@multitable} line or definition line. + +@item empty_spaces_after_close_brace +@anchor{Texinfo::Parser empty_spaces_after_close_brace} + +Spaces appearing after a closing brace, for some rare commands for which +this space should be ignorable (like @code{@@caption}). + +@item empty_spaces_before_paragraph +@anchor{Texinfo::Parser empty_spaces_before_paragraph} + +Space appearing before a paragraph beginning. + +@item raw +@anchor{Texinfo::Parser raw} + +Text in an environment where it should be kept as is (in @code{@@verbatim}, +@code{@@verb}, @code{@@html}, @code{@@macro} body). + +@item last_raw_newline +@anchor{Texinfo::Parser last_raw_newline} + +The last end of line in a raw block (except for @code{@@verbatim}). + +@item preamble_text +@anchor{Texinfo::Parser preamble_text} + +Text appearing before real content, including the @code{\input texinfo.tex}. + +@item space_at_end_menu_node +@anchor{Texinfo::Parser space_at_end_menu_node} + +@item after_description_line +@anchor{Texinfo::Parser after_description_line} + +Space after a node in the menu entry, when there is no description, +and space appearing after the description line. + +@end table + +@node Texinfo::Parser Types of container elements +@subsubsection Types of container elements + +The other types of element are the following. These are containers with +other elements appearing in their @code{contents}. + +@table @asis +@item text_root +@anchor{Texinfo::Parser text_root} + +@item document_root +@anchor{Texinfo::Parser document_root} + +@item root_line +@anchor{Texinfo::Parser root_line} + +These types correspond to document roots. @code{text_root} is the document +root when there is no @code{@@node} or sectioning command. When +such a command appears, a new root container is used, @code{document_root}, +and @code{text_root} becomes the first element in the contents of @code{document_root}. +@code{root_line} is the type of the root tree when parsing Texinfo line +fragments using @code{parse_texi_line}. + +@item preamble +@anchor{Texinfo::Parser preamble} + +This container holds the text appearing before the first content, including +the @code{\input texinfo.tex} line and following blank lines. + +@item preamble_before_setfilename +@anchor{Texinfo::Parser preamble_before_setfilename} + +This container holds everything that appears before @code{@@setfilename} +if @emph{IGNORE_BEFORE_SETFILENAME} parser option is set. + +@item paragraph +@anchor{Texinfo::Parser paragraph} + +A paragraph. The @code{contents} of a paragraph (like other container +elements for Texinfo content) are elements representing the contents of +the paragraph in the order they occur, such as simple text elements +without a @code{cmdname} or @code{type}, or @@-command elements for commands +appearing in the paragraph. + +@item preformatted +@anchor{Texinfo::Parser preformatted} + +Texinfo code within a format that is not filled. Happens within some +block commands like @code{@@example}, but also in menu (in menu descriptions, +menu comments...). + +@item brace_command_arg +@anchor{Texinfo::Parser brace_command_arg} + +@item brace_command_context +@anchor{Texinfo::Parser brace_command_context} + +@item line_arg +@anchor{Texinfo::Parser line_arg} + +@item block_line_arg +@anchor{Texinfo::Parser block_line_arg} + +Those containers occur within the @code{args} array of @@-commands taking an +argument. @emph{brace_command_arg} is used for the arguments to commands +taking arguments surrounded by braces (and in some cases separated by +commas). @emph{brace_command_context} is used for @@-commands with braces +that start a new context (@code{@@footnote}, @code{@@caption}, @code{@@math}). + +@emph{line_arg} is used for commands that take the texinfo code on the +rest of the line as their argument (for example (@code{@@settitle}, @code{@@node}, +@code{@@section} and similar). @emph{block_line_arg} is similar but is used for +commands that start a new block (which is to be ended with @code{@@end}). + +For example + +@verbatim + @code{in code} +@end verbatim + +leads to + +@verbatim + {'cmdname' => 'code', + 'args' => [{'type' => 'brace_command_arg', + 'contents' => [{'text' => 'in code'}]}]} +@end verbatim + +@item misc_arg +@anchor{Texinfo::Parser misc_arg} + +Used for the arguments to some special line commands whose arguments +aren't subject to the usual macro expansion. For example @code{@@set}, +@code{@@clickstyle}, @code{@@unmacro}, @code{@@comment}. The argument is associated to +the @emph{text} key. + +@item menu_entry +@anchor{Texinfo::Parser menu_entry} + +@item menu_entry_leading_text +@anchor{Texinfo::Parser menu_entry_leading_text} + +@item menu_entry_name +@anchor{Texinfo::Parser menu_entry_name} + +@item menu_entry_separator +@anchor{Texinfo::Parser menu_entry_separator} + +@item menu_entry_node +@anchor{Texinfo::Parser menu_entry_node} + +@item menu_entry_description +@anchor{Texinfo::Parser menu_entry_description} + +A @emph{menu_entry} holds a full menu entry, like + +@verbatim + * node:: description. +@end verbatim + +The different elements of the menu entry are directly in the +@emph{menu_entry} @code{args} array reference. + +@emph{menu_entry_leading_text} holds the star and following spaces. +@emph{menu_entry_name} is the menu entry name (if present), @emph{menu_entry_node} +corresponds to the node in the menu entry, @emph{menu_entry_separator} holds +the text after the node and before the description, in most cases +@code{:: }. Lastly, @emph{menu_entry_description} is for the description. + +@item menu_comment +@anchor{Texinfo::Parser menu_comment} + +The @emph{menu_comment} container holds what is between menu entries +in menus. For example in + +@verbatim + @menu + Menu title + + * entry:: + + Between entries + * other:: + @end menu +@end verbatim + +Both + +@verbatim + Menu title +@end verbatim + +and + +@verbatim + Between entries +@end verbatim + +will be in @emph{menu_comment}. + +@item macro_name +@anchor{Texinfo::Parser macro_name} + +@item macro_arg +@anchor{Texinfo::Parser macro_arg} + +Taken from @code{@@macro} definition and put in the @code{args} key array of +the macro, @emph{macro_name} is the type of the text fragment corresponding +to the macro name, @emph{macro_arg} is the type of the text fragments +correponding to macro formal arguments. + +@item before_item +@anchor{Texinfo::Parser before_item} + +A container for content before the first @code{@@item} of block @@-commands +with items (@code{@@table}, @code{@@multitable}, @code{@@enumerate}...). + +@item table_entry +@anchor{Texinfo::Parser table_entry} + +@item table_term +@anchor{Texinfo::Parser table_term} + +@item table_item +@anchor{Texinfo::Parser table_item} + +@item inter_item +@anchor{Texinfo::Parser inter_item} + +Those containers appear in @code{@@table}, @code{@@ftable} and @code{@@vtable}. +A @emph{table_entry} container contains an entire row of the table. +It contains a @emph{table_term} container, which holds all the @code{@@item} and +@code{@@itemx} lines. This is followed by a @emph{table_item} container, which +holds the content that is to go into the second column of the table. + +If there is any content before an @code{@@itemx} (normally only comments, +empty lines or maybe index entries are allowed), it will be in +a container with type @emph{inter_item}. + +@item def_line +@anchor{Texinfo::Parser def_line 1} + +@item def_item +@anchor{Texinfo::Parser def_item} + +@item inter_def_item +@anchor{Texinfo::Parser inter_def_item} + +The @emph{def_line} type is either associated with a container within a +definition command, or is the type of a definition command with a x +form, like @code{@@deffnx}. It holds the definition line arguments. +The container with type @emph{def_item} holds the definition text content. +Content appearing before a definition command with a x form is in +an @emph{inter_def_item} container. + +@item multitable_head +@anchor{Texinfo::Parser multitable_head} + +@item multitable_body +@anchor{Texinfo::Parser multitable_body} + +@item row +@anchor{Texinfo::Parser row} + +In @code{@@multitable}, a @emph{multitable_head} container contains all the rows +with @code{@@headitem}, while @emph{multitable_body} contains the rows associated +with @code{@@item}. A @emph{row} container contains the @code{@@item} and @@<tab> +forming a row. + +@item bracketed +@anchor{Texinfo::Parser bracketed} + +This a special type containing content in brackets in the context +where they are valid, in @code{@@math}. + +@item bracketed_def_content +@anchor{Texinfo::Parser bracketed_def_content} + +Content in brackets on definition command lines. + +@item def_aggregate +@anchor{Texinfo::Parser def_aggregate} + +Contains several elements that together are a single unit on a @@def* line. + +@item bracketed_multitable_prototype +@anchor{Texinfo::Parser bracketed_multitable_prototype} + +@item row_prototype +@anchor{Texinfo::Parser row_prototype} + +On @code{@@multitable} line, content in brackets is in +@emph{bracketed_multitable_prototype}, text not in brackets +is in @emph{row_prototype}. + +@end table + +@node Texinfo::Parser Information available in the extra key +@subsection Information available in the extra key + +@menu +* Texinfo@asis{::}Parser Extra keys available for more than one @@-command:: +* Texinfo@asis{::}Parser Extra keys specific of certain @@-commands or containers:: +@end menu + +@node Texinfo::Parser Extra keys available for more than one @@-command +@subsubsection Extra keys available for more than one @@-command + +@table @asis +@item end_command +@anchor{Texinfo::Parser end_command} + +The @code{@@end} associated to the block @@-command. + +@item missing_argument +@anchor{Texinfo::Parser missing_argument} + +Set for some @@-commands with line arguments and a missing argument. + +@item arg_line +@anchor{Texinfo::Parser arg_line} + +The string correspond to the line after the @@-command +for @@-commands that have special arguments on their line, +and for @code{@@macro} line. + +@item text_arg +@anchor{Texinfo::Parser text_arg} + +The string correspond to the line after the @@-command for @@-commands +that have an argument interpreted as simple text, like @code{@@setfilename}, +@code{@@end} or @code{@@documentencoding}. + +@item index_entry +@anchor{Texinfo::Parser index_entry} + +The index entry information (described in @ref{Texinfo::Parser index_entries,, index_entries} +in details) is associated to @@-commands that have an associated +index entry. + +@item misc_args +@anchor{Texinfo::Parser misc_args} + +An array holding strings, the arguments of @@-commands taking simple +textual arguments as arguments, like @code{@@everyheadingmarks}, +@code{@@frenchspacing}, @code{@@alias}, @code{@@synindex}, @code{@@columnfractions}. +Also filled for @code{@@set}, @code{@@clickstyle}, @code{@@unmacro} or @code{@@comment} +arguments. + +@item spaces_before_argument +@anchor{Texinfo::Parser spaces_before_argument} + +For @@-commands with opening brace followed by spaces held in a +@code{empty_spaces_before_argument} element, a reference to those spaces. + +@item spaces +@anchor{Texinfo::Parser spaces} + +For accent commands acting on one letter only, like @code{@@ringaccent} +appearing like + +@verbatim + @ringaccent A +@end verbatim + +there is a @emph{spaces} key which holds the spaces appearing between +the command and the argument. + +@end table + +@node Texinfo::Parser Extra keys specific of certain @@-commands or containers +@subsubsection Extra keys specific of certain @@-commands or containers + +@table @asis +@item @code{@@macro} +@anchor{Texinfo::Parser @code{@@macro}} + +@emph{invalid_syntax} is set if there was an error on the @code{@@macro} +line. @emph{arg_line} holds the line after @code{@@macro}. + +@item @code{@@node} +@anchor{Texinfo::Parser @code{@@node}} + +The arguments are in the @emph{nodes_manuals} array. Each +of the entries is a hash with a @emph{node_content} key for +an array holding the corresponding content, a @emph{manual_content} key +if there is an associated external manual name, and a @emph{normalized} +key for the normalized label, built as specified in the Texinfo manual +in the @strong{HTML Xref} node. + +An @emph{associated_section} key holds the tree element of the +sectioning command that follows the node. + +@item @code{@@part} +@anchor{Texinfo::Parser @code{@@part}} + +The next sectioning command is in @emph{part_associated_section}. + +@item sectioning command +@anchor{Texinfo::Parser sectioning command} + +The node preceding the command is in @emph{associated_node}. +The part preceding the command is in @emph{associated_part}. +If the level of the document was modified by @code{@@raisections} +or @code{@@lowersections}, the differential level is in @emph{sections_level}. + +@item @code{@@float} +@anchor{Texinfo::Parser @code{@@float}} + +@item @code{@@listoffloats} +@anchor{Texinfo::Parser @code{@@listoffloats}} + +If float has a second argument, and for @code{@@listoffloats} +argument there is a @emph{type} key which is also a hash reference, +with two keys. @emph{content} is an array holding the associated +contents, @emph{normalized} holds the normalized float type. + +@emph{caption} and @emph{shortcaption} holds the corresponding +tree elements for float. The @code{@@caption} or @code{@@shortcaption} +have the float tree element stored in @emph{float}. + +@item @code{@@float} +@anchor{Texinfo::Parser @code{@@float} 1} + +@item @code{@@anchor} +@anchor{Texinfo::Parser @code{@@anchor}} + +@@-commands that are targets for cross-references have a @emph{normalized} +key for the normalized label, built as specified in the Texinfo manual +in the @strong{HTML Xref} node. There is also a @emph{node_content} key for +an array holding the corresponding content. + +@code{@@anchor} also has @emph{region} set to the special region name if +in a special region (@code{@@copying}, @code{@@titlepage}). + +@item @code{@@ref} +@anchor{Texinfo::Parser @code{@@ref}} + +@item @code{@@xref} +@anchor{Texinfo::Parser @code{@@xref}} + +@item @code{@@pxref} +@anchor{Texinfo::Parser @code{@@pxref}} + +@item @code{@@inforef} +@anchor{Texinfo::Parser @code{@@inforef}} + +The @emph{node_argument} entry holds a parsed node entry, like +the one appearing in the @emph{nodes_manuals} array for @code{@@node}. + +@item @code{@@abbr} +@anchor{Texinfo::Parser @code{@@abbr}} + +@item @code{@@acronym} +@anchor{Texinfo::Parser @code{@@acronym}} + +The first argument normalized is in @emph{normalized}. + +@item definition command +@anchor{Texinfo::Parser definition command} + +@emph{def_command} holds the command name, without x if it is +an x form of a definition command. +@emph{original_def_cmdname} is the original def command. + +If it is an x form, it has @emph{not_after_command} set if not +appearing after the definition command without x. + +@item def_line +@anchor{Texinfo::Parser def_line 2} + +For each element in a def_line, the key @emph{def_role} holds a string +describing the meaning of the element. It is one of +@emph{category}, @emph{name}, @emph{class}, @emph{type}, @emph{arg}, @emph{typearg}, +@emph{spaces} or @emph{delimiter}, depending on the definition. + +The @emph{def_parsed_hash} hash reference has these strings as keys, +and the values are the corresponding elements. + +@item @code{@@multitable} +@anchor{Texinfo::Parser @code{@@multitable}} + +The key @emph{max_columns} holds the maximal number of columns. If there +are prototypes on the line they are in the array associated with +@emph{prototypes}. If there is a @code{@@columnfractions} as argument, then the +@emph{columnfractions} key is associated with the element for the +@@columnfractions command. + +@item @code{@@enumerate} +@anchor{Texinfo::Parser @code{@@enumerate}} + +The extra key @emph{enumerate_specification} contains the enumerate +argument. + +@item @code{@@itemize} +@anchor{Texinfo::Parser @code{@@itemize}} + +@item @code{@@table} +@anchor{Texinfo::Parser @code{@@table}} + +@item @code{@@vtable} +@anchor{Texinfo::Parser @code{@@vtable}} + +@item @code{@@ftable} +@anchor{Texinfo::Parser @code{@@ftable}} + +The @emph{command_as_argument} extra key points to the @@-command on +as argument on the @@-command line. + +@item paragraph +@anchor{Texinfo::Parser paragraph 1} + +The @emph{indent} or @emph{noindent} key value is set if the corresponding +@@-commands are associated with that paragraph. + +@item @code{@@item} in @code{@@enumerate} or @code{@@itemize} +@anchor{Texinfo::Parser @code{@@item} in @code{@@enumerate} or @code{@@itemize}} + +The @emph{item_number} extra key holds the number of this item. + +@item @code{@@item} and @code{@@tab} in @code{@@multitable} +@anchor{Texinfo::Parser @code{@@item} and @code{@@tab} in @code{@@multitable}} + +The @emph{cell_number} index key holds the index of the column of +the cell. + +@item row +@anchor{Texinfo::Parser row 1} + +The @emph{row_number} index key holds the index of the row in +the @code{@@multitable}. + +@item @code{@@author} +@anchor{Texinfo::Parser @code{@@author}} + +If in a @code{@@titlepage}, the titlepage is in @emph{titlepage}, if in +@code{@@quotation} or @code{@@smallquotation}, the corresponding tree element +is in @emph{quotation}. + +The author tree element is in the @emph{author} array of the @code{@@titlepage} +or the @code{@@quotation} or @code{@@smallquotation} it is associated with. + +@item @code{@@ifclear} +@anchor{Texinfo::Parser @code{@@ifclear}} + +@item @code{@@ifset} +@anchor{Texinfo::Parser @code{@@ifset}} + +The original line is in @emph{line}. + +@item @code{@@end} +@anchor{Texinfo::Parser @code{@@end}} + +The textual argument is in @emph{command_argument}. +The corresponding @@-command is in @emph{command}. + +@item @code{@@documentencoding} +@anchor{Texinfo::Parser @code{@@documentencoding}} + +The argument, normalized is in @emph{input_encoding_name} if it is recognized. +The corresponding perl encoding name is in @emph{input_perl_encoding}. + +@item @code{@@click} +@anchor{Texinfo::Parser @code{@@click}} + +In @emph{clickstyle} there is the current clickstyle command. + +@item @code{@@kbd} +@anchor{Texinfo::Parser @code{@@kbd}} + +@emph{code} is set depending on the context and @code{@@kbdinputstyle}. + +@item definfoenclose defined commands +@anchor{Texinfo::Parser definfoenclose defined commands} + +@emph{begin} holds the string beginning the definfoenclose, +@emph{end} holds the string ending the definfoenclose. + +@item menu_entry +@anchor{Texinfo::Parser menu_entry 1} + +The @emph{menu_entry_description} and @emph{menu_entry_name} keys +are associated with the corresponding tree elements. The +@emph{menu_entry_node} value is a hash with information about the parsed +node entry; its keys are the same as those appearing in the +elements of the @emph{nodes_manuals} array for @code{@@node}. + +@item empty_line_after_command +@anchor{Texinfo::Parser empty_line_after_command 1} + +The corresponding command is in @emph{command}. + +@item @code{@@inlinefmt} +@anchor{Texinfo::Parser @code{@@inlinefmt}} + +@item @code{@@inlineraw} +@anchor{Texinfo::Parser @code{@@inlineraw}} + +@item @code{@@inlinefmtifelse} +@anchor{Texinfo::Parser @code{@@inlinefmtifelse}} + +@item @code{@@inlineifclear} +@anchor{Texinfo::Parser @code{@@inlineifclear}} + +@item @code{@@inlineifset} +@anchor{Texinfo::Parser @code{@@inlineifset}} + +The first argument is in @emph{format}. If an argument has been determined +as being expanded by the Parser, the index of this argument is in +@emph{expand_index}. Index numbering begins at 0, but the first argument is +always the format or flag name, so, if set, it should be 1 or 2 for +@code{@@inlinefmtifelse}, and 1 for other commands. + +@end table + +@node Texinfo::Parser Other information set by the parser +@subsection Other information set by the parser + +The parser creates an array of nodes and stores this in the +@emph{nodes} key of the parser object. + +Each element in the tree corresponding to a node contaning a menu +has a @emph{menus} key which refers to an array of references to menu +elements occuring in the node. + +These are both used by the @code{Texinfo::Structuring} module. + +@node Texinfo::Parser SEE ALSO +@section SEE ALSO + +@url{http://www.gnu.org/s/texinfo/manual/texinfo/, Texinfo manual} + +@node Texinfo::Parser AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Report.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Report.texi new file mode 100644 index 0000000000..59bf76c2d7 --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Report.texi @@ -0,0 +1,209 @@ +@node Texinfo::Report +@chapter Texinfo::Report + +@menu +* Texinfo@asis{::}Report NAME:: +* Texinfo@asis{::}Report SYNOPSIS:: +* Texinfo@asis{::}Report DESCRIPTION:: +* Texinfo@asis{::}Report METHODS:: +* Texinfo@asis{::}Report AUTHOR:: +@end menu + +@node Texinfo::Report NAME +@section NAME + +Texinfo::Report - Error storing and string translations for Texinfo modules + +@node Texinfo::Report SYNOPSIS +@section SYNOPSIS + +@verbatim + @ISA = qw(Texinfo::Report); + + $converter->Texinfo::Report::new(); + + if ($warning_happened) { + $converter->line_warn(sprintf($converter->__("\@%s is wrongly used"), + $current->{'cmdname'}), $current->{'line_nr'}); + } + + my ($errors, $errors_count) = $converter->errors(); + foreach my $error_message (@$errors) { + warn $error_message->{'error_line'}; + } + + my $tree_translated = $converter->gdt('See {reference} in @cite{{book}}', + {'reference' => $tree_reference, + 'book' => {'text' => $book_name}}); +@end verbatim + +@node Texinfo::Report DESCRIPTION +@section DESCRIPTION + +The Texinfo::Report module helps with string translations and error +handling. It is used by the Texinfo modules Texinfo::Parser and +Texinfo::Convert::Converter. To use this module, the usual way is +to inherit Texinfo::Report methods and initialize the Texinfo::Report +variables for a @emph{$converter} object. This is done by calling +@code{Texinfo::Report::new()} on the @emph{$converter} object. This is done by +Texinfo::Convert::Converter, for instance, so every module that inherits +Texinfo::Convert::Converter can automatically use the Texinfo::Report +methods in an object-oriented way. + +Besides the @code{new} method, @code{gdt} is used for string translations, +@code{errors} for reporting errors, and the other methods to store errors +(and warnings). + +@node Texinfo::Report METHODS +@section METHODS + +No method is exported in the default case. + +The @code{new} method initializes Texinfo::Report related fields: + +@verbatim + $converter->Texinfo::Report::new() +@end verbatim + +The @code{gdt} method is used to translate strings to be output in +converted documents, and return a texinfo tree. + +@table @asis +@item $tree = $converter->gdt($string, $replaced_substrings, $mode) +@anchor{Texinfo::Report $tree = $converter->gdt($string@comma{} $replaced_substrings@comma{} $mode)} + +The @emph{$string} is a string to be translated. In the default case, +the function returns a Texinfo tree, as the string is +interpreted as Texinfo code after +translation. @emph{$replaced_substrings} is an optional +hash reference specifying some +substitution to be done after the translation. The key of +the @emph{$replaced_substrings} hash reference identifies what is to +be substituted, and the value is some string, texinfo tree or array content +that is substituted in the resulting texinfo tree. +In the string to be translated word in brace matching keys of +@emph{$replaced_substrings} are replaced. + +@emph{$mode} is an optional string which may modify how the function +behaves. The possible values are + +@table @asis +@item translated_text +@anchor{Texinfo::Report translated_text} + +In that case the string is not considered to be Texinfo, a plain string +that is returned after translation and substitution. The substitutions +may only be strings in that case. + +@end table + +For example in the following call, the string +@emph{See @{reference@} in @@cite@{@{book@}@}} is translated, then +parsed as a Texinfo string, with @emph{@{reference@}} substituted by +@emph{$tree_reference} in the resulting tree, and @emph{@{book@}} +replaced by the associated texinfo tree text element: + +@verbatim + $tree = $converter->gdt('See {reference} in @cite{{book}}', + {'reference' => $tree_reference, + 'book' => {'text' => $book_name}}); +@end verbatim + +@code{gdt} uses the information in the @emph{$converter} to know the +encoding and documentlanguage. More precisely, +@code{$converter->@{'encoding_name'@}}, @code{$converter->@{'perl_encoding'@}} +and @code{$converter->get_conf('documentlanguage')} are used. + +@code{gdt} uses a gettext-like infrastructure to retrieve the +translated strings, using the @emph{texinfo_document} domain. + +@end table + +The errors collected are available through the @code{errors} method, the other +methods allow registering errors and warnings. + +@table @asis +@item ($error_warnings_list, $error_count) = errors ($converter) +@anchor{Texinfo::Report ($error_warnings_list@comma{} $error_count) = errors ($converter)} + +This function returns as @emph{$error_count} the count of errors since +calling @code{new}. The @emph{$error_warnings_list} is an array of hash references +one for each error, warning or error line continuation. Each of these has +the following keys: + +@table @asis +@item type +@anchor{Texinfo::Report type} + +May be @code{warning}, or @code{error}. + +@item text +@anchor{Texinfo::Report text} + +The text of the error. + +@item error_line +@anchor{Texinfo::Report error_line} + +The text of the error formatted with the file name, line number and macro +name, as needed. + +@item line_nr +@anchor{Texinfo::Report line_nr} + +The line number of the error or warning. + +@item file_name +@anchor{Texinfo::Report file_name} + +The file name where the error or warning occurs. + +@item macro +@anchor{Texinfo::Report macro} + +The user macro name that is expanded at the location of +the error or warning. + +@end table + +@item $converter->line_warn($text, $line_nr) +@anchor{Texinfo::Report $converter->line_warn($text@comma{} $line_nr)} + +@item $converter->line_error($text, $line_nr) +@anchor{Texinfo::Report $converter->line_error($text@comma{} $line_nr)} + +Register a warning or an error. The @emph{$text} is the text of the +error or warning. The optional @emph{$line_nr} holds the information +on the error or warning location. It is associated with the @emph{line_nr} +key of Texinfo tree elements as described in @ref{Texinfo::Parser line_nr} +for the @@-commands. The @emph{$line_nr} structure is described in @ref{, errors,, error_warnings_list_error_count__errors_converter} +above. + +@item $converter->document_warn($text) +@anchor{Texinfo::Report $converter->document_warn($text)} + +@item $converter->document_error($text) +@anchor{Texinfo::Report $converter->document_error($text)} + +Register a document-wide error or warning. @emph{$text} is the error or +warning message. + +@item $converter->file_line_warn($text, $file, $line_nr) +@anchor{Texinfo::Report $converter->file_line_warn($text@comma{} $file@comma{} $line_nr)} + +Register the warning message @emph{$text} for file @emph{$file}, with, optionally +the line @emph{$line_nr} in the file. + +@item $converter->file_line_error($text, $file, $line_nr) +@anchor{Texinfo::Report $converter->file_line_error($text@comma{} $file@comma{} $line_nr)} + +Register the error message @emph{$text} for file @emph{$file}, with, optionally +the line @emph{$line_nr} in the file. + +@end table + +@node Texinfo::Report AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Structuring.texi b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Structuring.texi new file mode 100644 index 0000000000..f15808f7da --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Structuring.texi @@ -0,0 +1,414 @@ +@node Texinfo::Structuring +@chapter Texinfo::Structuring + +@menu +* Texinfo@asis{::}Structuring NAME:: +* Texinfo@asis{::}Structuring SYNOPSIS:: +* Texinfo@asis{::}Structuring DESCRIPTION:: +* Texinfo@asis{::}Structuring METHODS:: +* Texinfo@asis{::}Structuring SEE ALSO:: +* Texinfo@asis{::}Structuring AUTHOR:: +@end menu + +@node Texinfo::Structuring NAME +@section NAME + +Texinfo::Structuring - information on Texinfo::Parser tree + +@node Texinfo::Structuring SYNOPSIS +@section SYNOPSIS + +@verbatim + use Texinfo::Structuring qw(sectioning_structure nodes_tree number_floats + associate_internal_references split_by_node split_by_section split_pages + merge_indices sort_indices_by_letter sort_indices elements_directions + elements_file_directions); + # $tree is a Texinfo document tree. $parser is a Texinfo::Parser object. + my $sections_root = sectioning_structure ($parser, $tree); + my $top_node = nodes_tree($parser); + number_floats($parser->floats_information()); + associate_internal_references($parser); + my $elements; + if ($split_at_nodes) { + $elements = split_by_node($tree); + } else { + $elements = split_by_section($tree); + } + split_pages($elements, $split); + elements_directions($parser, $elements); + elements_file_directions($parser, $elements); + + my $index_names = $parser->indices_information(); + my $merged_index_entries + = merge_indices($index_names); + my $index_entries_sorted; + if ($sort_by_letter) { + $index_entries_sorted = sort_indices_by_letter($parser, + $merged_index_entries, $index_names); + } else { + $index_entries_sorted = sort_indices($parser, $merged_index_entries, + $index_names); + } + + +@end verbatim + +@node Texinfo::Structuring DESCRIPTION +@section DESCRIPTION + +Texinfo::Structuring first allows to collect informations on a Texinfo tree. +In most case, it also requires a parser object to do that job. Thanks to +@code{sectioning_structure} the hierarchy of sectioning commands is determined. +The node and menus tree is analysed with @code{nodes_tree}. Floats get their +standard numbering with @code{number_floats} and internal references are matched +up with nodes, floats or anchors with @code{associate_internal_references}. + +It is also possible to group the top-level contents of the tree, which consist +in nodes and sectioning commands into elements that group together a node and +the next sectioning element. With @code{split_by_node} nodes are considered +to be the main sectioning elements, while with @code{split_by_section} the +sectioning command elements are the main elements. The first mode is typical +of Info format, while the second correspond to a traditional book. +The elements may be further split in @emph{pages}, which are not pages as +in book pages, but more like web pages, and hold series of elements. + +The elements may have directions to other elements prepared +by @code{elements_directions}. @code{elements_file_directions} should also +set direction related to files, provided files are associated with +elements by the user. + +@code{merge_indices} may be used to merge indices, which may be sorted +with @code{sort_indices} or @code{sort_indices_by_letter} to sort by letters. + +Other miscellaneous methods include @code{set_menus_to_simple_menu} and +@code{menu_to_simple_menu} to change the menu texinfo tree, as well +as @code{insert_nodes_for_sectioning_commands} that adds nodes for +sectioning commands without nodes and @code{complete_tree_nodes_menus} +that completes the node menus based on the sectioning tree. + +@node Texinfo::Structuring METHODS +@section METHODS + +No method is exported in the default case. + +Most of those function references takes a Texinfo::Parser object +as argument, see @ref{Texinfo::Parser NAME}. + +@table @asis +@item $sections_root = sectioning_structure ($parser, $tree) +@anchor{Texinfo::Structuring $sections_root = sectioning_structure ($parser@comma{} $tree)} + +This function goes through the tree and gather information on +the document structure for sectioning commands. It returns the +root of the sectioning commands tree. + +For section elements, it sets: + +@table @asis +@item level +@anchor{Texinfo::Structuring level} + +The level in the sectioning tree hierarchy. 0 is for @code{@@top} or +@code{@@part}, 1 for @code{@@chapter}, @code{@@appendix}... This level is corrected +by @code{@@raisesections} and @code{@@lowersections}. + +@item number +@anchor{Texinfo::Structuring number} + +The sectioning element number. + +@item section_childs +@anchor{Texinfo::Structuring section_childs} + +An array holding sectioning elements children of the element. + +@item section_up +@anchor{Texinfo::Structuring section_up} + +@item section_prev +@anchor{Texinfo::Structuring section_prev} + +@item section_next +@anchor{Texinfo::Structuring section_next} + +The up, previous and next sectioning elements. + +@item toplevel_next +@anchor{Texinfo::Structuring toplevel_next} + +@item toplevel_prev +@anchor{Texinfo::Structuring toplevel_prev} + +@item toplevel_up +@anchor{Texinfo::Structuring toplevel_up} + +The next and previous and up sectioning elements of toplevel sectioning +elements (like @code{@@top}, @code{@@chapter}, @code{@@appendix}), not taking into +account @code{@@part} elements. + +@end table + +@item my $top_node = nodes_tree($parser) +@anchor{Texinfo::Structuring my $top_node = nodes_tree($parser)} + +Goes through menu and nodes and set directions. Returns the top +node. + +This functions sets: + +@table @asis +@item menu_child +@anchor{Texinfo::Structuring menu_child} + +The first child in the menu of the node. + +@item menu_up +@anchor{Texinfo::Structuring menu_up} + +@item menu_next +@anchor{Texinfo::Structuring menu_next} + +@item menu_prev +@anchor{Texinfo::Structuring menu_prev} + +Up, next and previous directions as set in menus. + +@item node_up +@anchor{Texinfo::Structuring node_up} + +@item node_prev +@anchor{Texinfo::Structuring node_prev} + +@item node_next +@anchor{Texinfo::Structuring node_next} + +Up, next and previous directions for the node. + +@end table + +@item number_floats($float_information) +@anchor{Texinfo::Structuring number_floats($float_information)} + +Number the floats as described in the Texinfo manual. Sets +the @emph{number} key of the float tree elements. + +@item associate_internal_references($parser) +@anchor{Texinfo::Structuring associate_internal_references($parser)} + +Verify that internal references (@code{@@ref} and similar without +fourth of fifth argument) have an associated node, anchor or float. +Set the @emph{label} key in the @emph{extra} hash of the reference tree +element to the associated labeled tree element. + +@item warn_non_empty_parts($parser) +@anchor{Texinfo::Structuring warn_non_empty_parts($parser)} + +Register a warning in @code{$parser} for each @code{@@part} that is not empty. + +@item $elements = split_by_node($tree) +@anchor{Texinfo::Structuring $elements = split_by_node($tree)} + +Returns a reference array of elements where a node is associated to +the following sectioning commands. Sectioning commands without nodes +are also with the previous node, while nodes without sectioning commands +are alone in their elements. + +Elements are regular tree items with type @emph{element}, the +associated nodes and sectioning tree items are in the array associated +with the @emph{contents} key. They have directions, namely @emph{element_next} +and @emph{element_prev} pointing to the previous and the next element. + +In the @emph{extra} hash they have + +@table @asis +@item no_node +@anchor{Texinfo::Structuring no_node} + +A special case, if there are no nodes in the document, the value is set. + +@item node +@anchor{Texinfo::Structuring node} + +@item element_command +@anchor{Texinfo::Structuring element_command} + +The node command associated with the element. + +@item section +@anchor{Texinfo::Structuring section} + +The sectioning command associated with the element node. + +@end table + +@item $elements = split_by_section($tree) +@anchor{Texinfo::Structuring $elements = split_by_section($tree)} + +Similarly with @code{split_by_node}, returns an array of elements. This time, +lone nodes are associated with the previous sections and lone sections +makes up an element. + +The extra hash keys set are the same, except that @emph{element_command} is +the sectioning command associated with the element, and @emph{no_node} is +replaced by @emph{no_section}. + +@item $pages = split_pages($elements, $split) +@anchor{Texinfo::Structuring $pages = split_pages($elements@comma{} $split)} + +The elements from the array reference argument have an extra @emph{first_in_page} +value set to the first element on the unit, and based on the +value of @emph{$split}. The possible values for @emph{$split} are + +@table @asis +@item chapter +@anchor{Texinfo::Structuring chapter} + +The elements are split at chapter or other toplevel sectioning elements. + +@item node +@anchor{Texinfo::Structuring node 1} + +Each element has its own page. + +@item section +@anchor{Texinfo::Structuring section 1} + +The elements are split at sectioning commands below chapter. + +@item value evaluating to false +@anchor{Texinfo::Structuring value evaluating to false} + +No splitting, only one page is returned, holding all the elements. + +@end table + +@item elements_directions($parser, $elements) +@anchor{Texinfo::Structuring elements_directions($parser@comma{} $elements)} + +Directions are set up for the elements in the array reference given in +argument. The corresponding hash reference is in +@code{@{'extra'@}->@{'directions'@}} +and keys correspond to directions while values are elements. + +The following directions are set up: + +@table @asis +@item This +@anchor{Texinfo::Structuring This} + +The element itself. + +@item Forward +@anchor{Texinfo::Structuring Forward} + +Element next. + +@item Back +@anchor{Texinfo::Structuring Back} + +Previous element. + +@item NodeForward +@anchor{Texinfo::Structuring NodeForward} + +Following node element in reading order. It is the next node, or the +first in menu or the next of the up node. + +@item NodeBack +@anchor{Texinfo::Structuring NodeBack} + +Preceding node element. + +@item NodeUp +@anchor{Texinfo::Structuring NodeUp} + +@item NodeNext +@anchor{Texinfo::Structuring NodeNext} + +@item NodePrev +@anchor{Texinfo::Structuring NodePrev} + +The up, next and previous node elements. + +@item Up +@anchor{Texinfo::Structuring Up} + +@item Next +@anchor{Texinfo::Structuring Next} + +@item Prev +@anchor{Texinfo::Structuring Prev} + +The up, next and previous section elements. + +@item FastForward +@anchor{Texinfo::Structuring FastForward} + +The next top level section element. + +@item FastBack +@anchor{Texinfo::Structuring FastBack} + +For top level elements, the previous top level element. For other elements +the up top level element. For example, for a chapter element it is the +previous chapter, for a subsection element it is the chapter element +that contains the subsection. + +@item FastForward +@anchor{Texinfo::Structuring FastForward 1} + +The next top level element. + +@end table + +@item elements_file_directions($parser, $elements) +@anchor{Texinfo::Structuring elements_file_directions($parser@comma{} $elements)} + +In the directions reference described above for @code{elements_directions}, sets +the @emph{PrevFile} and @code{NextFile} directions to the elements in previous and +following files. + +The API for association of pages/elements to files is not defined yet. + +@item $merged_entries = merge_indices($index_names) +@anchor{Texinfo::Structuring $merged_entries = merge_indices($index_names)} + +Using informations returned by @ref{Texinfo::Parser indices_information}, +a structure holding all the index entries by index name is returned, +with all the entries of merged indices merged with those of the indice +merged into. + +The @emph{$merged_entries} returned is a hash reference whose +keys are the index names and values arrays of index entry structures +described in details in @ref{Texinfo::Parser index_entries}. + +@item $index_entries_sorted = sort_indices_by_letter($parser, $merged_index_entries, $index_names) +@anchor{Texinfo::Structuring $index_entries_sorted = sort_indices_by_letter($parser@comma{} $merged_index_entries@comma{} $index_names)} + +@item $index_entries_sorted = sort_indices($parser, $merged_index_entries, $index_names) +@anchor{Texinfo::Structuring $index_entries_sorted = sort_indices($parser@comma{} $merged_index_entries@comma{} $index_names)} + +These functions first sets a plain text key for each index entry, used for +sorting. In both cases, a hash reference with index names as keys is returned. + +When sorting by letter, an array reference of letter hash references is +associated with each index name. Each letter hash reference has two +keys, a @emph{letter} key with the letter, and an @emph{entries} key with an array +reference of sorted index entries beginning with the letter. + +When simply sorting, the array of the sorted indes entries is associated +with the index name. + +@end table + +@node Texinfo::Structuring SEE ALSO +@section SEE ALSO + +@url{http://www.gnu.org/s/texinfo/manual/texinfo/, Texinfo manual}, +@ref{Texinfo::Parser NAME}. + +@node Texinfo::Structuring AUTHOR +@section AUTHOR + +Patrice Dumas, <pertusus@@free.fr> + diff --git a/macros/texinfo/texinfo/doc/tp_api/tp_api.texi b/macros/texinfo/texinfo/doc/tp_api/tp_api.texi new file mode 100644 index 0000000000..f8c6b5844c --- /dev/null +++ b/macros/texinfo/texinfo/doc/tp_api/tp_api.texi @@ -0,0 +1,305 @@ +\input texinfo +@setfilename tp_api.info +@documentencoding utf-8 +@settitle Texinfo perl module + +@contents + +@ifnottex +@node Top +@top Texinfo perl module +@end ifnottex + +@menu +* Texinfo@asis{::}Common:: +* Texinfo@asis{::}Parser:: +* Texinfo@asis{::}Structuring:: +* Texinfo@asis{::}Report:: +* Texinfo@asis{::}Encoding:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization:: +* Texinfo@asis{::}Convert@asis{::}Text:: +* Texinfo@asis{::}Convert@asis{::}Texinfo:: +* Texinfo@asis{::}Convert@asis{::}Converter:: +* Texinfo@asis{::}Convert@asis{::}Unicode:: +* Texinfo@asis{::}Convert@asis{::}Info:: +* Texinfo@asis{::}Convert@asis{::}DocBook:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML:: +* Texinfo@asis{::}Convert@asis{::}Plaintext:: +* Texinfo@asis{::}Convert@asis{::}HTML:: + +@detailmenu + --- The Detailed Node Listing --- + +Texinfo::Common + +* Texinfo@asis{::}Common NAME:: +* Texinfo@asis{::}Common SYNOPSIS:: +* Texinfo@asis{::}Common DESCRIPTION:: +* Texinfo@asis{::}Common COMMAND CLASSES:: +* Texinfo@asis{::}Common METHODS:: +* Texinfo@asis{::}Common SEE ALSO:: +* Texinfo@asis{::}Common AUTHOR:: +* Texinfo@asis{::}Common NAME:: +* Texinfo@asis{::}Common SYNOPSIS:: +* Texinfo@asis{::}Common DESCRIPTION:: +* Texinfo@asis{::}Common COMMAND CLASSES:: +* Texinfo@asis{::}Common METHODS:: +* Texinfo@asis{::}Common SEE ALSO:: +* Texinfo@asis{::}Common AUTHOR:: + +Texinfo::Parser + +* Texinfo@asis{::}Parser NAME:: +* Texinfo@asis{::}Parser SYNOPSIS:: +* Texinfo@asis{::}Parser DESCRIPTION:: +* Texinfo@asis{::}Parser METHODS:: +* Texinfo@asis{::}Parser TEXINFO TREE:: +* Texinfo@asis{::}Parser SEE ALSO:: +* Texinfo@asis{::}Parser AUTHOR:: +* Texinfo@asis{::}Parser NAME:: +* Texinfo@asis{::}Parser SYNOPSIS:: +* Texinfo@asis{::}Parser DESCRIPTION:: +* Texinfo@asis{::}Parser METHODS:: +* Texinfo@asis{::}Parser TEXINFO TREE:: +* Texinfo@asis{::}Parser SEE ALSO:: +* Texinfo@asis{::}Parser AUTHOR:: + +METHODS + +* Texinfo@asis{::}Parser Initialization:: +* Texinfo@asis{::}Parser Parsing Texinfo text:: +* Texinfo@asis{::}Parser Getting information on the document:: +* Texinfo@asis{::}Parser Texinfo Parser options:: +* Texinfo@asis{::}Parser Initialization:: +* Texinfo@asis{::}Parser Parsing Texinfo text:: +* Texinfo@asis{::}Parser Getting information on the document:: +* Texinfo@asis{::}Parser Texinfo Parser options:: + +TEXINFO TREE + +* Texinfo@asis{::}Parser Element keys:: +* Texinfo@asis{::}Parser Element types:: +* Texinfo@asis{::}Parser Information available in the extra key:: +* Texinfo@asis{::}Parser Other information set by the parser:: +* Texinfo@asis{::}Parser Element keys:: +* Texinfo@asis{::}Parser Element types:: +* Texinfo@asis{::}Parser Information available in the extra key:: +* Texinfo@asis{::}Parser Other information set by the parser:: + +Element types + +* Texinfo@asis{::}Parser Types for command elements:: +* Texinfo@asis{::}Parser Types for text elements:: +* Texinfo@asis{::}Parser Types of container elements:: +* Texinfo@asis{::}Parser Types for command elements:: +* Texinfo@asis{::}Parser Types for text elements:: +* Texinfo@asis{::}Parser Types of container elements:: + +Information available in the extra key + +* Texinfo@asis{::}Parser Extra keys available for more than one @@-command:: +* Texinfo@asis{::}Parser Extra keys specific of certain @@-commands or containers:: +* Texinfo@asis{::}Parser Extra keys available for more than one @@-command:: +* Texinfo@asis{::}Parser Extra keys specific of certain @@-commands or containers:: + +Texinfo::Structuring + +* Texinfo@asis{::}Structuring NAME:: +* Texinfo@asis{::}Structuring SYNOPSIS:: +* Texinfo@asis{::}Structuring DESCRIPTION:: +* Texinfo@asis{::}Structuring METHODS:: +* Texinfo@asis{::}Structuring SEE ALSO:: +* Texinfo@asis{::}Structuring AUTHOR:: +* Texinfo@asis{::}Structuring NAME:: +* Texinfo@asis{::}Structuring SYNOPSIS:: +* Texinfo@asis{::}Structuring DESCRIPTION:: +* Texinfo@asis{::}Structuring METHODS:: +* Texinfo@asis{::}Structuring SEE ALSO:: +* Texinfo@asis{::}Structuring AUTHOR:: + +Texinfo::Report + +* Texinfo@asis{::}Report NAME:: +* Texinfo@asis{::}Report SYNOPSIS:: +* Texinfo@asis{::}Report DESCRIPTION:: +* Texinfo@asis{::}Report METHODS:: +* Texinfo@asis{::}Report AUTHOR:: +* Texinfo@asis{::}Report NAME:: +* Texinfo@asis{::}Report SYNOPSIS:: +* Texinfo@asis{::}Report DESCRIPTION:: +* Texinfo@asis{::}Report METHODS:: +* Texinfo@asis{::}Report AUTHOR:: + +Texinfo::Encoding + +* Texinfo@asis{::}Encoding NAME:: +* Texinfo@asis{::}Encoding SYNOPSIS:: +* Texinfo@asis{::}Encoding DESCRIPTION:: +* Texinfo@asis{::}Encoding METHODS:: +* Texinfo@asis{::}Encoding AUTHOR:: +* Texinfo@asis{::}Encoding NAME:: +* Texinfo@asis{::}Encoding SYNOPSIS:: +* Texinfo@asis{::}Encoding DESCRIPTION:: +* Texinfo@asis{::}Encoding METHODS:: +* Texinfo@asis{::}Encoding AUTHOR:: + +Texinfo::Convert::NodeNameNormalization + +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization NAME:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization METHODS:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization AUTHOR:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization NAME:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization METHODS:: +* Texinfo@asis{::}Convert@asis{::}NodeNameNormalization AUTHOR:: + +Texinfo::Convert::Text + +* Texinfo@asis{::}Convert@asis{::}Text NAME:: +* Texinfo@asis{::}Convert@asis{::}Text SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Text DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Text METHODS:: +* Texinfo@asis{::}Convert@asis{::}Text AUTHOR:: +* Texinfo@asis{::}Convert@asis{::}Text NAME:: +* Texinfo@asis{::}Convert@asis{::}Text SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Text DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Text METHODS:: +* Texinfo@asis{::}Convert@asis{::}Text AUTHOR:: + +Texinfo::Convert::Texinfo + +* Texinfo@asis{::}Convert@asis{::}Texinfo NAME:: +* Texinfo@asis{::}Convert@asis{::}Texinfo SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Texinfo DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Texinfo METHODS:: +* Texinfo@asis{::}Convert@asis{::}Texinfo AUTHOR:: +* Texinfo@asis{::}Convert@asis{::}Texinfo NAME:: +* Texinfo@asis{::}Convert@asis{::}Texinfo SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Texinfo DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Texinfo METHODS:: +* Texinfo@asis{::}Convert@asis{::}Texinfo AUTHOR:: + +Texinfo::Convert::Converter + +* Texinfo@asis{::}Convert@asis{::}Converter NAME:: +* Texinfo@asis{::}Convert@asis{::}Converter SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Converter DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Converter METHODS:: +* Texinfo@asis{::}Convert@asis{::}Converter SEE ALSO:: +* Texinfo@asis{::}Convert@asis{::}Converter AUTHOR:: +* Texinfo@asis{::}Convert@asis{::}Converter POD ERRORS:: +* Texinfo@asis{::}Convert@asis{::}Converter NAME:: +* Texinfo@asis{::}Convert@asis{::}Converter SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Converter DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Converter METHODS:: +* Texinfo@asis{::}Convert@asis{::}Converter SEE ALSO:: +* Texinfo@asis{::}Convert@asis{::}Converter AUTHOR:: +* Texinfo@asis{::}Convert@asis{::}Converter POD ERRORS:: + +METHODS + +* Texinfo@asis{::}Convert@asis{::}Converter Initialization:: +* Texinfo@asis{::}Convert@asis{::}Converter Helper methods:: +* Texinfo@asis{::}Convert@asis{::}Converter Initialization:: +* Texinfo@asis{::}Convert@asis{::}Converter Helper methods:: + +Texinfo::Convert::Unicode + +* Texinfo@asis{::}Convert@asis{::}Unicode NAME:: +* Texinfo@asis{::}Convert@asis{::}Unicode SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Unicode DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Unicode METHODS:: +* Texinfo@asis{::}Convert@asis{::}Unicode AUTHOR:: +* Texinfo@asis{::}Convert@asis{::}Unicode NAME:: +* Texinfo@asis{::}Convert@asis{::}Unicode SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Unicode DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Unicode METHODS:: +* Texinfo@asis{::}Convert@asis{::}Unicode AUTHOR:: + +Texinfo::Convert::Info + +* Texinfo@asis{::}Convert@asis{::}Info NAME:: +* Texinfo@asis{::}Convert@asis{::}Info SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Info DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Info METHODS:: +* Texinfo@asis{::}Convert@asis{::}Info AUTHOR:: +* Texinfo@asis{::}Convert@asis{::}Info NAME:: +* Texinfo@asis{::}Convert@asis{::}Info SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Info DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Info METHODS:: +* Texinfo@asis{::}Convert@asis{::}Info AUTHOR:: + +Texinfo::Convert::DocBook + +* Texinfo@asis{::}Convert@asis{::}DocBook NAME:: +* Texinfo@asis{::}Convert@asis{::}DocBook SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}DocBook DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}DocBook METHODS:: +* Texinfo@asis{::}Convert@asis{::}DocBook AUTHOR:: +* Texinfo@asis{::}Convert@asis{::}DocBook NAME:: +* Texinfo@asis{::}Convert@asis{::}DocBook SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}DocBook DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}DocBook METHODS:: +* Texinfo@asis{::}Convert@asis{::}DocBook AUTHOR:: + +Texinfo::Convert::TexinfoXML + +* Texinfo@asis{::}Convert@asis{::}TexinfoXML NAME:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML METHODS:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML AUTHOR:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML NAME:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML METHODS:: +* Texinfo@asis{::}Convert@asis{::}TexinfoXML AUTHOR:: + +Texinfo::Convert::Plaintext + +* Texinfo@asis{::}Convert@asis{::}Plaintext NAME:: +* Texinfo@asis{::}Convert@asis{::}Plaintext SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Plaintext DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Plaintext METHODS:: +* Texinfo@asis{::}Convert@asis{::}Plaintext AUTHOR:: +* Texinfo@asis{::}Convert@asis{::}Plaintext NAME:: +* Texinfo@asis{::}Convert@asis{::}Plaintext SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}Plaintext DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}Plaintext METHODS:: +* Texinfo@asis{::}Convert@asis{::}Plaintext AUTHOR:: + +Texinfo::Convert::HTML + +* Texinfo@asis{::}Convert@asis{::}HTML NAME:: +* Texinfo@asis{::}Convert@asis{::}HTML SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}HTML DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}HTML METHODS:: +* Texinfo@asis{::}Convert@asis{::}HTML AUTHOR:: +* Texinfo@asis{::}Convert@asis{::}HTML NAME:: +* Texinfo@asis{::}Convert@asis{::}HTML SYNOPSIS:: +* Texinfo@asis{::}Convert@asis{::}HTML DESCRIPTION:: +* Texinfo@asis{::}Convert@asis{::}HTML METHODS:: +* Texinfo@asis{::}Convert@asis{::}HTML AUTHOR:: +@end detailmenu +@end menu + +@include api_includes/Texinfo-Common.texi +@include api_includes/Texinfo-Parser.texi +@include api_includes/Texinfo-Structuring.texi +@include api_includes/Texinfo-Report.texi +@include api_includes/Texinfo-Encoding.texi +@include api_includes/Texinfo-Convert-NodeNameNormalization.texi +@include api_includes/Texinfo-Convert-Text.texi +@include api_includes/Texinfo-Convert-Texinfo.texi +@include api_includes/Texinfo-Convert-Converter.texi +@include api_includes/Texinfo-Convert-Unicode.texi +@include api_includes/Texinfo-Convert-Info.texi +@include api_includes/Texinfo-Convert-DocBook.texi +@include api_includes/Texinfo-Convert-TexinfoXML.texi +@include api_includes/Texinfo-Convert-Plaintext.texi +@include api_includes/Texinfo-Convert-HTML.texi + +@bye diff --git a/macros/texinfo/texinfo/doc/txi-ca.tex b/macros/texinfo/texinfo/doc/txi-ca.tex new file mode 100644 index 0000000000..675475da36 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-ca.tex @@ -0,0 +1,62 @@ +% txi-ca.tex -- Catalan translations for texinfo.tex. +% +% Copyright (C) 2015 Walter Garcia-Fontes +% +% This txi-ca.tex file is free software; you can redistribute it and/or +% modify it under the terms of the GNU General Public License as +% published by the Free Software Foundation; either version 3 of the +% License, or (at your option) any later version. +% +% This txi-ca.tex file is distributed in the hope that it will be +% useful, but WITHOUT ANY WARRANTY; without even the implied warranty +% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +% General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +% Set up fixed words for Spanish. + +\txisetlanguage{catalan}{2}{2} + +\plainfrenchspacing + +\gdef\putwordAppendix{Annex} +\gdef\putwordChapter{Cap\'{\dotless{i}}tol} +\gdef\putwordfile{fitxer} +\gdef\putwordIndexIsEmpty{(L'\'Index \'es buit)} +\gdef\putwordIndexNonexistent{(No existeix l'\'Index)} +\gdef\putwordInfo{Info} +\gdef\putwordMethodon{M\`etode de} +\gdef\putwordNoTitle{Sense T\'{\dotless{i}}tol} +\gdef\putwordof{de} +\gdef\putwordon{de} +\gdef\putwordpage{p\`agina} +\gdef\putwordsection{secci\'o} +\gdef\putwordSection{Secci\'o} +\gdef\putwordsee{vegeu} +\gdef\putwordSee{Vegeu} +\gdef\putwordShortTOC{Resum del Contingut} +\gdef\putwordTOC{\'Index General} +% +\gdef\putwordMJan{gener} +\gdef\putwordMFeb{febrer} +\gdef\putwordMMar{març} +\gdef\putwordMApr{abril} +\gdef\putwordMMay{maig} +\gdef\putwordMJun{juny} +\gdef\putwordMJul{juliol} +\gdef\putwordMAug{agost} +\gdef\putwordMSep{setembre} +\gdef\putwordMOct{octubre} +\gdef\putwordMNov{novembre} +\gdef\putwordMDec{desembre} +% +\gdef\putwordDefmac{Macro} +\gdef\putwordDefspec{Forma Especial} +\gdef\putwordDefivar{Variable d'Inst\`ancia} +\gdef\putwordDefvar{Variable} +\gdef\putwordDefopt{Opci\'o d'Usuari} +\gdef\putwordDeffunc{Funci\'o} + +\endinput diff --git a/macros/texinfo/texinfo/doc/txi-cs.tex b/macros/texinfo/texinfo/doc/txi-cs.tex new file mode 100644 index 0000000000..a20287c01f --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-cs.tex @@ -0,0 +1,76 @@ +% txi-cs.tex -- Czech translations for texinfo.tex. +% +% Copyright 1999, 2000, 2007, 2008 Free Software Foundation. +% +% Authors: +% Vladimir Michl <Vladimir.Michl@mujweb.cz> +% Stepan Kasal <kasal@ucw.cz> +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. + +\txisetlanguage{czech}{2}{3} + +\plainfrenchspacing + +\gdef\putwordAppendix{Plohy} +\gdef\putwordChapter{Kapitola} +\gdef\putwordfile{soubor} +\gdef\putwordin{v~knize} +\gdef\putwordIndexIsEmpty{(Rejstk je przdn.)} +\gdef\putwordIndexNonexistent{(Rejstk neexistuje.)} +\gdef\putwordInfo{Info} +\gdef\putwordInstanceVariableof{Promnn pro instance tdy} +\gdef\putwordMethodon{Metoda tdy} +\gdef\putwordNoTitle{Bez nadpisu} +\gdef\putwordof{tdy} +\global\let\putwordon\putwordof +\gdef\putwordpage{strnka} +\gdef\putwordsection{oddl} +\gdef\putwordSection{Oddl} +\gdef\putwordsee{viz} +\gdef\putwordSee{Viz} +\gdef\putwordShortTOC{Strun obsah} +\gdef\putwordTOC{Obsah} +% +\gdef\putwordMJan{ledna} +\gdef\putwordMFeb{nora} +\gdef\putwordMMar{bezna} +\gdef\putwordMApr{dubna} +\gdef\putwordMMai{kvtna} +\gdef\putwordMJun{ervna} +\gdef\putwordMJul{ervence} +\gdef\putwordMAug{srpna} +\gdef\putwordMSep{z} +\gdef\putwordMOct{jna} +\gdef\putwordMNov{listopadu} +\gdef\putwordMDec{prosince} +% +\gdef\putwordDefmac{Makro} +\gdef\putwordDefspec{Speciln forma} +\gdef\putwordDefvar{Promnn} +\gdef\putwordDefopt{Volby} +\gdef\putwordDeffunc{Funkce} +% +% Redefine \today to produce Czech +% preferred dates such as 28. januar 1999. +% +\gdef\today{% + \number\day.\nobreak\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMai\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \penalty3000\relax\space\number\year} +% diff --git a/macros/texinfo/texinfo/doc/txi-de.tex b/macros/texinfo/texinfo/doc/txi-de.tex new file mode 100644 index 0000000000..8df874c433 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-de.tex @@ -0,0 +1,81 @@ +% txi-de.tex -- German translations for texinfo.tex. +% +% Copyright 1999, 2007, 2008 Free Software Foundation, Inc. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the license, or (at +% your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +% Written by Karl Heinz Marbaise, 18. January 1999, <kama@hippo.fido.de> + +\txisetlanguage{ngerman}{2}{2} + +\plainfrenchspacing + +% german translation of the used words. +% Don't use checking because if it is our turn they have +% been defined. +\gdef\putwordAppendix{Anhang} +\gdef\putwordChapter{Kapitel} +\gdef\putwordfile{Datei} +\gdef\putwordin{in} +\gdef\putwordInfo{Info} +\gdef\putwordMethodon{Methode von} +\gdef\putwordon{auf} +\gdef\putwordof{von} +\gdef\putwordpage{Seite} +\gdef\putwordsection{Abschnitt} +\gdef\putwordSection{Abschnitt} +\gdef\putwordsee{siehe} +\gdef\putwordSee{Siehe} +\gdef\putwordShortTOC{Kurzverzeichnis} +\gdef\putwordTOC{Inhaltsverzeichnis} +%% +\gdef\putwordNoTitle{Kein Titel} +%% +%% New definition for the output of months. +\gdef\putwordMJan{Januar} +\gdef\putwordMFeb{Februar} +\gdef\putwordMMar{M\"arz} +\gdef\putwordMApr{April} +\gdef\putwordMMai{Mai} +\gdef\putwordMJun{Juni} +\gdef\putwordMJul{Juli} +\gdef\putwordMAug{August} +\gdef\putwordMSep{September} +\gdef\putwordMOct{Oktober} +\gdef\putwordMNov{November} +\gdef\putwordMDec{Dezember} +%% +%% some hyphenation for german language. Might be changed. +\hyphenation{An-hang} +%%\hyphenation{mini-buf-fer mini-buf-fers} +%%\hyphenation{eshell} +%%\hyphenation{white-space} +%% +%% Index handling should also work correct in german +\gdef\putwordIndexNonexistent{(Index ist nicht vorhanden)} +\gdef\putwordIndexIsEmpty{(Der Index ist leer)} +%% +%% \defmac +\gdef\putwordDefmac{Makro} +%% \defspec +\gdef\putwordDefspec{Spezial Form} +%% \defivar +\gdef\putwordDefivar{exemplar Variable} +%% \defvar leave unchanged because no difference in +%% writing but in phonectics. +\gdef\putwordDefvar{Variable} +%% \defopt +\gdef\putwordDefopt{Benutzer Option} +%% \deffun +\gdef\putwordDeffunc{Funktion} diff --git a/macros/texinfo/texinfo/doc/txi-en.tex b/macros/texinfo/texinfo/doc/txi-en.tex new file mode 100644 index 0000000000..5124c56f5b --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-en.tex @@ -0,0 +1,73 @@ +% txi.en.tex -- English non-translations for texinfo.tex. This is read +% when a source document says @documentlanguage en (which might happen +% after another @documentlanguage). The actual values are the same as +% the defaults. +% +% Copyright 1999, 2007, 2008 Free Software Foundation. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. + +\txisetlanguage{USenglish}{2}{3} + +\plainnonfrenchspacing + +\gdef\putwordAppendix{Appendix} +\gdef\putwordChapter{Chapter} +\gdef\putworderror{error} +\gdef\putwordfile{file} +\gdef\putwordin{in} +\gdef\putwordIndexIsEmpty{(Index is empty)} +\gdef\putwordIndexNonexistent{(Index is nonexistent)} +\gdef\putwordInfo{Info} +\gdef\putwordInstanceVariableof{Instance Variable of} +\gdef\putwordMethodon{Method on} +\gdef\putwordNoTitle{No Title} +\gdef\putwordof{of} +\gdef\putwordon{on} +\gdef\putwordpage{page} +\gdef\putwordsection{section} +\gdef\putwordSection{Section} +\gdef\putwordsee{see} +\gdef\putwordSee{See} +\gdef\putwordShortTOC{Short Contents} +\gdef\putwordTOC{Table of Contents} +% +\gdef\putwordMJan{January} +\gdef\putwordMFeb{February} +\gdef\putwordMMar{March} +\gdef\putwordMApr{April} +\gdef\putwordMMay{May} +\gdef\putwordMJun{June} +\gdef\putwordMJul{July} +\gdef\putwordMAug{August} +\gdef\putwordMSep{September} +\gdef\putwordMOct{October} +\gdef\putwordMNov{November} +\gdef\putwordMDec{December} +% +\gdef\putwordDefmac{Macro} +\gdef\putwordDefspec{Special Form} +\gdef\putwordDefvar{Variable} +\gdef\putwordDefopt{User Option} +\gdef\putwordDeffunc{Function} + +% Produces Day Month Year style of output. +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} diff --git a/macros/texinfo/texinfo/doc/txi-es.tex b/macros/texinfo/texinfo/doc/txi-es.tex new file mode 100644 index 0000000000..2deee85aad --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-es.tex @@ -0,0 +1,63 @@ +% txi-es.tex -- Spanish translations for texinfo.tex. +% +% Copyright 1999, 2007, 2008, 2015 by Adrian Perez Jorge. +% +% This txi-es.tex file is free software; you can redistribute it and/or +% modify it under the terms of the GNU General Public License as +% published by the Free Software Foundation; either version 3 of the +% License, or (at your option) any later version. +% +% This txi-es.tex file is distributed in the hope that it will be +% useful, but WITHOUT ANY WARRANTY; without even the implied warranty +% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +% General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +% Set up fixed words for Spanish. + +\txisetlanguage{spanish}{2}{2} + +\plainfrenchspacing + +\gdef\putwordAppendix{Ap\'endice} +\gdef\putwordChapter{Cap\'{\char16{}}tulo} +\gdef\putwordfile{archivo} +\gdef\putwordIndexIsEmpty{(El \'Indice est\'a vac\'{\char16{}}o)} +\gdef\putwordIndexNonexistent{(No existe el \'Indice)} +\gdef\putwordInfo{Info} +\gdef\putwordin{en} +\gdef\putwordMethodon{M\'etodo de} +\gdef\putwordNoTitle{Sin T\'{\char{16}}tulo} +\gdef\putwordof{de} +\gdef\putwordon{de} +\gdef\putwordpage{p\'agina} +\gdef\putwordsection{secci\'on} +\gdef\putwordSection{Secci\'on} +\gdef\putwordsee{v\'ease} +\gdef\putwordSee{V\'ease} +\gdef\putwordShortTOC{Resumen del Contenido} +\gdef\putwordTOC{\'Indice General} +% +\gdef\putwordMJan{enero} +\gdef\putwordMFeb{febrero} +\gdef\putwordMMar{marzo} +\gdef\putwordMApr{abril} +\gdef\putwordMMay{mayo} +\gdef\putwordMJun{junio} +\gdef\putwordMJul{julio} +\gdef\putwordMAug{agosto} +\gdef\putwordMSep{septiembre} +\gdef\putwordMOct{octubre} +\gdef\putwordMNov{noviembre} +\gdef\putwordMDec{diciembre} +% +\gdef\putwordDefmac{Macro} +\gdef\putwordDefspec{Forma Especial} +\gdef\putwordDefivar{Variable de Instancia} +\gdef\putwordDefvar{Variable} +\gdef\putwordDefopt{Opci\'on de Usuario} +\gdef\putwordDeffunc{Funci\'on} + +\endinput diff --git a/macros/texinfo/texinfo/doc/txi-fr.tex b/macros/texinfo/texinfo/doc/txi-fr.tex new file mode 100644 index 0000000000..595227ff35 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-fr.tex @@ -0,0 +1,75 @@ +% txi-fr.tex -- French translations for texinfo.tex. +% +% Copyright (C) 1999, 2007, 2008 Free Software Foundation. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. + +% Set up fixed words for French. +% Translated by Laurent Bourbeau <bourbeau@progiciels-bpi.ca> +% Translation date: le 10 dcembre 1999. +% Transmitted to: Karl Berry <karl@cs.umb.edu> + +\txisetlanguage{french}{2}{3} + +\plainfrenchspacing + +\gdef\putwordAppendix{Annexe} +\gdef\putwordChapter{Chapitre} +\gdef\putwordfile{fichier} +\gdef\putwordin{dans} +\gdef\putwordIndexIsEmpty{(Index est vide)} +\gdef\putwordIndexNonexistent{(Index n'existe pas)} +\gdef\putwordInfo{Info} +\gdef\putwordInstanceVariableof{Variable d'instance de} +\gdef\putwordMethodon{M\'ethode sur} +\gdef\putwordNoTitle{Sans Titre} +\gdef\putwordof{de} +\gdef\putwordon{sur} +\gdef\putwordpage{page} +\gdef\putwordsection{section} +\gdef\putwordSection{Section} +\gdef\putwordsee{voir} +\gdef\putwordSee{Voir} +\gdef\putwordShortTOC{Sommaire} +\gdef\putwordTOC{Table des mati\`eres} +% +\gdef\putwordMJan{janvier} +\gdef\putwordMFeb{f\'evrier} +\gdef\putwordMMar{mars} +\gdef\putwordMApr{avril} +\gdef\putwordMMay{mai} +\gdef\putwordMJun{juin} +\gdef\putwordMJul{juillet} +\gdef\putwordMAug{ao\^ut} +\gdef\putwordMSep{septembre} +\gdef\putwordMOct{octobre} +\gdef\putwordMNov{novembre} +\gdef\putwordMDec{d\'ecembre} +% +\gdef\putwordDefmac{Macro} +\gdef\putwordDefspec{Forme Sp\'eciale} +\gdef\putwordDefvar{Variable} +\gdef\putwordDefopt{Option de l'usager} +\gdef\putwordDeffunc{Fonction} + +% Produces Day Month Year style of output. +% French datation - for instance: 10 janvier 2000. +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} diff --git a/macros/texinfo/texinfo/doc/txi-hu.tex b/macros/texinfo/texinfo/doc/txi-hu.tex new file mode 100644 index 0000000000..d14a9705f3 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-hu.tex @@ -0,0 +1,89 @@ +% txi-hu.tex -- Hungarian translations for texinfo.tex. +% +% Copyright 1999, 2007, 2008 Free Software Foundation, Inc. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the license, or (at +% your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. + +\txisetlanguage{hungarian}{2}{2} + +\plainfrenchspacing + +% Don't use checking because if it is our turn they have +% been defined. +\gdef\putwordAppendix{függelék} +\gdef\putwordChapter{fejezet} +\gdef\putwordfile{fájl} +\gdef\putwordin{in} +\gdef\putwordInfo{Info} +\gdef\putwordMethodon{Metódus itt:} +\gdef\putwordon{ezen:} +\gdef\putwordof{ebben:} +\gdef\putwordpage{oldal} +\gdef\putwordsection{rész} +\gdef\putwordSection{rész} +\gdef\putwordsee{lásd} +\gdef\putwordSee{Lásd} +\gdef\putwordShortTOC{Áttekintés} +\gdef\putwordTOC{Tartalomjegyzék} +%% +\gdef\putwordNoTitle{Nincs cím} +%% +%% New definition for the output of months. +\gdef\putwordMJan{Január} +\gdef\putwordMFeb{Február} +\gdef\putwordMMar{Március} +\gdef\putwordMApr{Április} +\gdef\putwordMMai{Május} +\gdef\putwordMJun{Június} +\gdef\putwordMJul{Július} +\gdef\putwordMAug{Augusztus} +\gdef\putwordMSep{Szeptember} +\gdef\putwordMOct{Október} +\gdef\putwordMNov{November} +\gdef\putwordMDec{December} +\gdef\putwordIndexNonexistent{(Nemlétező index)} +\gdef\putwordIndexIsEmpty{(Üres index)} +%% +%% \defmac +\gdef\putwordDefmac{Makró} +%% \defspec +\gdef\putwordDefspec{Speciális forma} +%% \defivar +\gdef\putwordDefivar{Példaváltozó} +%% \defvar leave unchanged because no difference in +%% writing but in phonectics. +\gdef\putwordDefvar{Változó} +%% \defopt +\gdef\putwordDefopt{Felhasználói opció} +%% \deffun +\gdef\putwordDeffunc{Függvény} + +%%% +%%% Date stamp +%%% Produces y-m-d style of output. +%%% 4-05-07 == 2007. m\'ajus 4. +%%% +\gdef\Today{\number\year. \ifcase\month\or % Mai d†tum + janu\'ar\or febru\'ar\or m\'arcius\or + \'aprilis\or m\'ajus\or j\'unius\or + j\'ulius\or augusztus\or szeptember\or + okt\'ober\or november\or december\fi + \space\ifcase\day\or + 1.\or 2.\or 3.\or 4.\or 5.\or + 6.\or 7.\or 8.\or 9.\or 10.\or + 11.\or 12.\or 13.\or 14.\or 15.\or + 16.\or 17.\or 18.\or 19.\or 20.\or + 21.\or 22.\or 23.\or 24.\or 25.\or + 26.\or 27.\or 28.\or 29.\or 30.\or + 31.\fi} diff --git a/macros/texinfo/texinfo/doc/txi-is.tex b/macros/texinfo/texinfo/doc/txi-is.tex new file mode 100644 index 0000000000..4c286626ce --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-is.tex @@ -0,0 +1,69 @@ +% txi-is.tex -- Texinfo support for Icelandic, version 1.0 (2009/03/18). +% Based on txi-en.tex (version 1.5, 2007/07/01) and icelandic.dtx (1.1g, +% 2005/03/30). +% +% Copyright (C) 2009 Arni Magnusson +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. + +\txisetlanguage{icelandic}{2}{2} + +\gdef\putwordAppendix{Vi{\dh}auki} +\gdef\putwordChapter{Kafli} +\gdef\putwordfile{skr\'a} +\gdef\putwordin{\'{\dotless{i}}} +\gdef\putwordIndexIsEmpty{(Atri{\dh}isor{\dh}askr\'a er t\'om)} +\gdef\putwordIndexNonexistent{(Atri{\dh}isor{\dh}askr\'a er ekki til)} +\gdef\putwordInfo{Info} +\gdef\putwordInstanceVariableof{Tilviksbreyta \'{\dotless{i}}} +\gdef\putwordMethodon{A{\dh}fer{\dh} fyrir} +\gdef\putwordNoTitle{Enginn titill} +\gdef\putwordof{\'{\dotless{i}}} +\gdef\putwordon{fyrir} +\gdef\putwordpage{bls.{}} +\gdef\putwordsection{undirkafli} +\gdef\putwordSection{Undirkafli} +\gdef\putwordsee{sj\'a} +\gdef\putwordSee{Sj\'a} +\gdef\putwordShortTOC{Stutt efnisyfirlit} +\gdef\putwordTOC{Efnisyfirlit} +% +\gdef\putwordMJan{jan\'uar} +\gdef\putwordMFeb{febr\'uar} +\gdef\putwordMMar{mars} +\gdef\putwordMApr{apr\'{\dotless{i}}l} +\gdef\putwordMMay{ma\'{\dotless{i}}} +\gdef\putwordMJun{j\'uni} +\gdef\putwordMJul{j\'ul\'{\dotless{i}}} +\gdef\putwordMAug{\'ag\'ust} +\gdef\putwordMSep{september} +\gdef\putwordMOct{okt\'ober} +\gdef\putwordMNov{n\'ovember} +\gdef\putwordMDec{desember} +% +\gdef\putwordDefmac{Fj\"olvi} +\gdef\putwordDefspec{S\'erstakt form} +\gdef\putwordDefvar{Breyta} +\gdef\putwordDefopt{Notendaval} +\gdef\putwordDeffunc{Fall} + +% Produces Day Month Year style of output. +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} diff --git a/macros/texinfo/texinfo/doc/txi-it.tex b/macros/texinfo/texinfo/doc/txi-it.tex new file mode 100644 index 0000000000..ca7c797184 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-it.tex @@ -0,0 +1,69 @@ +% txi-it.tex -- Italian translations for texinfo.tex +% +% Copyright 1999, 2007, 2008 Free Software Foundation. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. + +\txisetlanguage{italian}{2}{2} + +\plainfrenchspacing + +\gdef\putwordAppendix{Appendice} +\gdef\putwordChapter{Capitolo} +\gdef\putwordfile{file} +\gdef\putwordin{in} +\gdef\putwordIndexIsEmpty{(L'indice \'e vuoto)} +\gdef\putwordIndexNonexistent{(L'indice non esiste)} +\gdef\putwordInfo{Info} +\gdef\putwordInstanceVariableof{Variabile di istanza di} +\gdef\putwordMethodon{Metodo di} +\gdef\putwordNoTitle{Nessun titolo} +\gdef\putwordof{di} +\gdef\putwordon{su} +\gdef\putwordpage{pagina} +\gdef\putwordsection{sezione} +\gdef\putwordSection{Sezione} +\gdef\putwordsee{vedi} +\gdef\putwordSee{Vedi} +\gdef\putwordShortTOC{Sommario abbreviato} +\gdef\putwordTOC{Sommario} +% +\gdef\putwordMJan{Gennaio} +\gdef\putwordMFeb{Febbraio} +\gdef\putwordMMar{Marzo} +\gdef\putwordMApr{Aprile} +\gdef\putwordMMay{Maggio} +\gdef\putwordMJun{Giugno} +\gdef\putwordMJul{Luglio} +\gdef\putwordMAug{Agosto} +\gdef\putwordMSep{Settembre} +\gdef\putwordMOct{Ottobre} +\gdef\putwordMNov{Novembre} +\gdef\putwordMDec{Dicembre} +% +\gdef\putwordDefmac{Macro} +\gdef\putwordDefspec{Forma speciale} +\gdef\putwordDefvar{Variabile} +\gdef\putwordDefopt{Opzione} +\gdef\putwordDeffunc{Funzione} + +% Produces Day Month Year style of output. +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} diff --git a/macros/texinfo/texinfo/doc/txi-ja.tex b/macros/texinfo/texinfo/doc/txi-ja.tex new file mode 100644 index 0000000000..0374efe1d3 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-ja.tex @@ -0,0 +1,487 @@ +% txi-ja.tex -- Japanese translations and font definitions for texinfo.tex. +% +% Copyright 1999, 2007, 2008, 2016 Free Software Foundation, Inc. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the license, or (at +% your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +% Written by Masamichi Hosoda, 5 May 2016, <trueroad@trueroad.jp> + +\txisetlanguage{USenglish}{2}{3} + +\plainnonfrenchspacing + +\gdef\putwordAppendix{付録} +\gdef\putwordChapter{Chapter} +\gdef\putworderror{エラー} +\gdef\putwordfile{ファイル} +\gdef\putwordin{in} +\gdef\putwordIndexIsEmpty{(インデックスが空です)} +\gdef\putwordIndexNonexistent{(インデックスがありません)} +\gdef\putwordInfo{Info} +\gdef\putwordInstanceVariableof{Instance Variable of} +\gdef\putwordMethodon{Method on} +\gdef\putwordNoTitle{無題} +\gdef\putwordof{of} +\gdef\putwordon{on} +\gdef\putwordpage{p.} +\gdef\putwordsection{section} +\gdef\putwordSection{Section} +\gdef\putwordsee{see} +\gdef\putwordSee{See} +\gdef\putwordShortTOC{簡単な目次} +\gdef\putwordTOC{目次} +% +\gdef\putwordMJan{1月} +\gdef\putwordMFeb{2月} +\gdef\putwordMMar{3月} +\gdef\putwordMApr{4月} +\gdef\putwordMMay{5月} +\gdef\putwordMJun{6月} +\gdef\putwordMJul{7月} +\gdef\putwordMAug{8月} +\gdef\putwordMSep{9月} +\gdef\putwordMOct{10月} +\gdef\putwordMNov{11月} +\gdef\putwordMDec{12月} +% +\gdef\putwordDefmac{マクロ} +\gdef\putwordDefspec{特殊フォーム} +\gdef\putwordDefvar{変数} +\gdef\putwordDefopt{ユーザオプション} +\gdef\putwordDeffunc{関数} + +% Produces Year Month Day style of output. +\def\today{% + \number\year 年\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\day 日} + + +% +% Japanese font definitions +% + +\ifx\txijapackage\thisisundefined + \errmessage{Required CJK package is not found. + Use `texinfo-ja.tex' instead of `texinfo.tex'} +\else + + % + % For LuaTeX + % + \ifx\luatexversion\thisisundefined + \else + % Definitions for a main text size of 11pt. (The default in Texinfo.) + % Japanese font size is muliplied by 0.962216. + \let\definealphabetictextfontsizexi\definetextfontsizexi + \gdef\definetextfontsizexi{% + % Text fonts (11.2pt, magstep1). + \jfont\textmc{file:ipaexm.ttf:jfm=ujis} at 10.78pt + \jfont\textgt{file:ipaexg.ttf:jfm=ujis} at 10.78pt + + % Fonts for indices, footnotes, small examples (9pt). + \jfont\smallmc{file:ipaexm.ttf:jfm=ujis} at 8.66pt + \jfont\smallgt{file:ipaexg.ttf:jfm=ujis} at 8.66pt + + % Fonts for small examples (8pt). + \jfont\smallermc{file:ipaexm.ttf:jfm=ujis} at 7.70pt + \jfont\smallergt{file:ipaexg.ttf:jfm=ujis} at 7.70pt + + % Fonts for title page (20.4pt): + \jfont\titlemc{file:ipaexm.ttf:jfm=ujis} at 19.63pt + \jfont\titlegt{file:ipaexg.ttf:jfm=ujis} at 19.63pt + + % Chapter (and unnumbered) fonts (17.28pt). + \jfont\chapmc{file:ipaexm.ttf:jfm=ujis} at 16.63pt + \jfont\chapgt{file:ipaexg.ttf:jfm=ujis} at 16.63pt + + % Section fonts (14.4pt). + \jfont\secmc{file:ipaexm.ttf:jfm=ujis} at 13.86pt + \jfont\secgt{file:ipaexg.ttf:jfm=ujis} at 13.86pt + + % Subsection fonts (13.15pt). + \jfont\ssecmc{file:ipaexm.ttf:jfm=ujis} at 12.65pt + \jfont\ssecgt{file:ipaexg.ttf:jfm=ujis} at 12.65pt + + % Reduced fonts for @acro in text (10pt). + \jfont\reducedmc{file:ipaexm.ttf:jfm=ujis} at 9.62pt + \jfont\reducedgt{file:ipaexg.ttf:jfm=ujis} at 9.62pt + + % Fonts for short table of contents. + \jfont\shortcontmc{file:ipaexm.ttf:jfm=ujis} at 11.55pt + \jfont\shortcontgt{file:ipaexg.ttf:jfm=ujis} at 11.55pt + + \definealphabetictextfontsizexi + } + + % Definitions for a main text size of 10pt. + % Japanese font size is muliplied by 0.962216. + \let\definealphabetictextfontsizex\definetextfontsizex + \gdef\definetextfontsizex{% + % Text fonts (10pt). + \jfont\textmc{file:ipaexm.ttf:jfm=ujis} at 9.62pt + \jfont\textgt{file:ipaexg.ttf:jfm=ujis} at 9.62pt + + % Fonts for indices, footnotes, small examples (9pt). + \jfont\smallmc{file:ipaexm.ttf:jfm=ujis} at 8.66pt + \jfont\smallgt{file:ipaexg.ttf:jfm=ujis} at 8.66pt + + % Fonts for small examples (8pt). + \jfont\smallermc{file:ipaexm.ttf:jfm=ujis} at 7.70pt + \jfont\smallergt{file:ipaexg.ttf:jfm=ujis} at 7.70pt + + % Fonts for title page (20.4pt): + \jfont\titlemc{file:ipaexm.ttf:jfm=ujis} at 19.63pt + \jfont\titlegt{file:ipaexg.ttf:jfm=ujis} at 19.63pt + + % Chapter fonts (14.4pt). + \jfont\chapmc{file:ipaexm.ttf:jfm=ujis} at 13.86pt + \jfont\chapgt{file:ipaexg.ttf:jfm=ujis} at 13.86pt + + % Section fonts (12pt). + \jfont\secmc{file:ipaexm.ttf:jfm=ujis} at 11.55pt + \jfont\secgt{file:ipaexg.ttf:jfm=ujis} at 11.55pt + + % Subsection fonts (10pt). + \jfont\ssecmc{file:ipaexm.ttf:jfm=ujis} at 9.62pt + \jfont\ssecgt{file:ipaexg.ttf:jfm=ujis} at 9.62pt + + % Reduced fonts for @acro in text (9pt). + \jfont\reducedmc{file:ipaexm.ttf:jfm=ujis} at 8.66pt + \jfont\reducedgt{file:ipaexg.ttf:jfm=ujis} at 8.66pt + + % Fonts for short table of contents. + \jfont\shortcontmc{file:ipaexm.ttf:jfm=ujis} at 11.55pt + \jfont\shortcontgt{file:ipaexg.ttf:jfm=ujis} at 11.55pt + + \definealphabetictextfontsizex + } + + % Ignore LuaTeX-ja added line end comment + % https://osdn.jp/ticket/browse.php?group_id=5593&tid=36096 + % + % Re-define texinfo.tex's \parseargusing + \def\parseargusing#1#2{% + \def\argtorun{#2}% + \begingroup + \ifx\ltjlineendcomment\thisisundefined + % Ignore U+FFFFF for LuaTeX-ja <= 20160208.0 + \catcode"FFFFF=9 + \else + % Ignore the character \ltjlineendcomment for LuaTeX-ja > 20160208.0 + \catcode\ltjlineendcomment=9 + \fi + \obeylines + \spaceisspace + #1% + \parseargline\empty% Insert the \empty token, see \finishparsearg below. + } + % Re-define texinfo.tex's \comment + \def\comment{\begingroup \catcode`\^^M=\active% + \ifx\ltjlineendcomment\thisisundefined + % Ignore U+FFFFF for LuaTeX-ja <= 20160208.0 + \catcode"FFFFF=9% + \else + % Ignore the character \ltjlineendcomment for LuaTeX-ja > 20160208.0 + \catcode\ltjlineendcomment=9% + \fi + \catcode`\@=\other \catcode`\{=\other \catcode`\}=\other\commentxxx}% + % Re-let \comment related macros + \let\setfilename=\comment + \let\dircategory=\comment + \let\definfoenclose=\comment + \let\footnotestyle=\comment + % Re-define texinfo.tex's \c + \def\c{\begingroup \catcode`\^^M=\active% + \ifx\ltjlineendcomment\thisisundefined + % Ignore U+FFFFF for LuaTeX-ja <= 20160208.0 + \catcode"FFFFF=9% + \else + % Ignore the character \ltjlineendcomment for LuaTeX-ja > 20160208.0 + \catcode\ltjlineendcomment=9% + \fi + \catcode`\@=\other \catcode`\{=\other \catcode`\}=\other% + \cxxx} + % Re-let \c related macro + \let\texinfoc=\c + \fi % LuaTeX + + % + % For XeTeX + % + \ifx\XeTeXrevision\thisisundefined + \else + % Fix some Japanese character class + % (unicode-letters.tex is wrong.) + \def\do#1{\XeTeXcharclass"#1=1 } + \do{3041}\do{3043}\do{3045}\do{3047}\do{3049}\do{3063} + \do{3083}\do{3085}\do{3087}\do{308E}\do{3095}\do{3096} + \do{30A1}\do{30A3}\do{30A5}\do{30A7}\do{30A9}\do{30C3} + \do{30E3}\do{30E5}\do{30E7}\do{30EE}\do{30F5}\do{30F6} + \do{30FC}\do{31F0}\do{31F1}\do{31F2}\do{31F3}\do{31F4} + \do{31F5}\do{31F6}\do{31F7}\do{31F8}\do{31F9}\do{31FA} + \do{31FB}\do{31FC}\do{31FD}\do{31FE}\do{31FF} + + % Add some character class + \do{2015}\do{2016}\do{2025}\do{2030}\do{2032}\do{2033} + \do{203B}\do{2103}\do{212B} + + \do{2500}\do{2501}\do{2502}\do{2503}\do{250C}\do{250F} + \do{2510}\do{2513}\do{2514}\do{2517}\do{2518}\do{251B} + \do{251C}\do{251D}\do{2520}\do{2523}\do{2524}\do{2525} + \do{2528}\do{252B}\do{252C}\do{252F}\do{2530}\do{2533} + \do{2534}\do{2537}\do{2538}\do{253B}\do{253C}\do{253F} + \do{2542}\do{254B} + + \do{25A0}\do{25A1}\do{25B2}\do{25B3}\do{25BC}\do{25BD} + \do{25C6}\do{25C7}\do{25CB}\do{25CE}\do{25CF}\do{25EF} + \do{2605}\do{2606}\do{2640}\do{2642} + + \do{3000} + + % Setting Japanese font instead of Chinese font + \def\setjafont#1{% + \let\zhfont#1\let\zhpunctfont#1% + \let\zhextafont#1\let\zhextbfont#1% + } + + % Definitions for a main text size of 11pt. (The default in Texinfo.) + % Japanese font size is muliplied by 0.962216. + \let\definealphabetictextfontsizexi\definetextfontsizexi + \gdef\definetextfontsizexi{% + % Text fonts (11.2pt, magstep1). + \font\textmczzz"[ipaexm.ttf]:mapping=tex-text" at 10.78pt + \font\textgtzzz"[ipaexg.ttf]:mapping=tex-text" at 10.78pt + \def\textmc{\setjafont\textmczzz} + \def\textgt{\setjafont\textgtzzz} + + % Fonts for indices, footnotes, small examples (9pt). + \font\smallmczzz"[ipaexm.ttf]:mapping=tex-text" at 8.66pt + \font\smallgtzzz"[ipaexg.ttf]:mapping=tex-text" at 8.66pt + \def\smallmc{\setjafont\smallmczzz} + \def\smallgt{\setjafont\smallgtzzz} + + % Fonts for small examples (8pt). + \font\smallermczzz"[ipaexm.ttf]:mapping=tex-text" at 7.70pt + \font\smallergtzzz"[ipaexg.ttf]:mapping=tex-text" at 7.70pt + \def\smallermc{\setjafont\smallermczzz} + \def\smallergt{\setjafont\smallergtzzz} + + % Fonts for title page (20.4pt): + \font\titlemczzz"[ipaexm.ttf]:mapping=tex-text" at 19.63pt + \font\titlegtzzz"[ipaexg.ttf]:mapping=tex-text" at 19.63pt + \def\titlemc{\setjafont\titlemczzz} + \def\titlegt{\setjafont\titlegtzzz} + + % Chapter (and unnumbered) fonts (17.28pt). + \font\chapmczzz"[ipaexm.ttf]:mapping=tex-text" at 16.63pt + \font\chapgtzzz"[ipaexg.ttf]:mapping=tex-text" at 16.63pt + \def\chapmc{\setjafont\chapmczzz} + \def\chapgt{\setjafont\chapgtzzz} + + % Section fonts (14.4pt). + \font\secmczzz"[ipaexm.ttf]:mapping=tex-text" at 13.86pt + \font\secgtzzz"[ipaexg.ttf]:mapping=tex-text" at 13.86pt + \def\secmc{\setjafont\secmczzz} + \def\secgt{\setjafont\secgtzzz} + + % Subsection fonts (13.15pt). + \font\ssecmczzz"[ipaexm.ttf]:mapping=tex-text" at 12.65pt + \font\ssecgtzzz"[ipaexg.ttf]:mapping=tex-text" at 12.65pt + \def\ssecmc{\setjafont\ssecmczzz} + \def\ssecgt{\setjafont\ssecgtzzz} + + % Reduced fonts for @acro in text (10pt). + \font\reducedmczzz"[ipaexm.ttf]:mapping=tex-text" at 9.62pt + \font\reducedgtzzz"[ipaexg.ttf]:mapping=tex-text" at 9.62pt + \def\reducedmc{\setjafont\reducedmczzz} + \def\reducedgt{\setjafont\reducedgtzzz} + + % Fonts for short table of contents. + \font\shortcontmczzz"[ipaexm.ttf]:mapping=tex-text" at 11.55pt + \font\shortcontgtzzz"[ipaexg.ttf]:mapping=tex-text" at 11.55pt + \def\shortcontmc{\setjafont\shortcontmczzz} + \def\shortcontgt{\setjafont\shortcontgtzzz} + + \definealphabetictextfontsizexi + } + + % Definitions for a main text size of 10pt. + % Japanese font size is muliplied by 0.962216. + \let\definealphabetictextfontsizex\definetextfontsizex + \gdef\definetextfontsizex{% + % Text fonts (10pt). + \font\textmczzz"[ipaexm.ttf]:mapping=tex-text" at 9.62pt + \font\textgtzzz"[ipaexg.ttf]:mapping=tex-text" at 9.62pt + \def\textmc{\setjafont\textmczzz} + \def\textgt{\setjafont\textgtzzz} + + % Fonts for indices, footnotes, small examples (9pt). + \font\smallmczzz"[ipaexm.ttf]:mapping=tex-text" at 8.66pt + \font\smallgtzzz"[ipaexg.ttf]:mapping=tex-text" at 8.66pt + \def\smallmc{\setjafont\smallmczzz} + \def\smallgt{\setjafont\smallgtzzz} + + % Fonts for small examples (8pt). + \font\smallermczzz"[ipaexm.ttf]:mapping=tex-text" at 7.70pt + \font\smallergtzzz"[ipaexg.ttf]:mapping=tex-text" at 7.70pt + \def\smallermc{\setjafont\smallermczzz} + \def\smallergt{\setjafont\smallergtzzz} + + % Fonts for title page (20.4pt): + \font\titlemczzz"[ipaexm.ttf]:mapping=tex-text" at 19.63pt + \font\titlegtzzz"[ipaexg.ttf]:mapping=tex-text" at 19.63pt + \def\titlemc{\setjafont\titlemczzz} + \def\titlegt{\setjafont\titlegtzzz} + + % Chapter fonts (14.4pt). + \font\chapmczzz"[ipaexm.ttf]:mapping=tex-text" at 13.86pt + \font\chapgtzzz"[ipaexg.ttf]:mapping=tex-text" at 13.86pt + \def\chapmc{\setjafont\chapmczzz} + \def\chapgt{\setjafont\chapgtzzz} + + % Section fonts (12pt). + \font\secmczzz"[ipaexm.ttf]:mapping=tex-text" at 11.55pt + \font\secgtzzz"[ipaexg.ttf]:mapping=tex-text" at 11.55pt + \def\secmc{\setjafont\secmczzz} + \def\secgt{\setjafont\secgtzzz} + + % Subsection fonts (10pt). + \font\ssecmczzz"[ipaexm.ttf]:mapping=tex-text" at 9.62pt + \font\ssecgtzzz"[ipaexg.ttf]:mapping=tex-text" at 9.62pt + \def\ssecmc{\setjafont\ssecmczzz} + \def\ssecgt{\setjafont\ssecgtzzz} + + % Reduced fonts for @acro in text (9pt). + \font\reducedmczzz"[ipaexm.ttf]:mapping=tex-text" at 8.66pt + \font\reducedgtzzz"[ipaexg.ttf]:mapping=tex-text" at 8.66pt + \def\reducedmc{\setjafont\reducedmczzz} + \def\reducedgt{\setjafont\reducedgtzzz} + + % Fonts for short table of contents. + \font\shortcontmczzz"[ipaexm.ttf]:mapping=tex-text" at 11.55pt + \font\shortcontgtzzz"[ipaexg.ttf]:mapping=tex-text" at 11.55pt + \def\shortcontmc{\setjafont\shortcontmczzz} + \def\shortcontgt{\setjafont\shortcontgtzzz} + + \definealphabetictextfontsizex + } + + % Japanese line break settings + \XeTeXlinebreaklocale "ja_JP" + \XeTeXlinebreakskip=0em plus 0.1em minus 0.01em + \XeTeXlinebreakpenalty=0 + + % For copy & paste Unicode characters (XeTeX 0.99995+) + \ifx\XeTeXgenerateactualtext\thisisundefined + \else + \XeTeXgenerateactualtext=1 + \fi + + \fi % XeTeX + + \iftxinativeunicodecapable + + % Sync fonts + + \let\alphabeticrm\rm + \gdef\rm{\alphabeticrm\tenmc} + + \let\alphabeticit\it + \gdef\it{\alphabeticit\tenmc} + + \let\alphabeticsl\sl + \gdef\sl{\alphabeticsl\tengt} + + \let\alphabeticbf\bf + \gdef\bf{\alphabeticbf\tengt} + + \let\alphabetictt\tt + \gdef\tt{\alphabetictt\tengt} + + % Add fonts + + \let\alphabetictextfonts\textfonts + \gdef\textfonts{% + \alphabetictextfonts + \let\tenmc\textmc + \let\tengt\textgt + } + + \let\alphabetictitlefonts\titlefonts + \gdef\titlefonts{% + \alphabetictitlefonts + \let\tenmc\titlemc + \let\tengt\titlegt + } + + \let\alphabeticchapfonts\chapfonts + \gdef\chapfonts{% + \alphabeticchapfonts + \let\tenmc\chapmc + \let\tengt\chapgt + } + + \let\alphabeticsecfonts\secfonts + \gdef\secfonts{% + \alphabeticsecfonts + \let\tenmc\secmc + \let\tengt\secgt + } + + \let\alphabeticsubsecfonts\subsecfonts + \gdef\subsecfonts{% + \alphabeticsubsecfonts + \let\tenmc\ssecmc + \let\tengt\ssecgt + } + + \global\let\subsubsecfonts\subsecfonts + + \let\alphabeticreducedfonts\reducedfonts + \gdef\reducedfonts{% + \alphabeticreducedfonts + \let\tenmc\reducedmc + \let\tengt\reducedgt + } + + \let\alphabeticsmallfonts\smallfonts + \gdef\smallfonts{% + \alphabeticsmallfonts + \let\tenmc\smallmc + \let\tengt\smallgt + } + + \let\alphabeticsmallerfonts\smallerfonts + \gdef\smallerfonts{% + \alphabeticsmallerfonts + \let\tenmc\smallermc + \let\tengt\smallergt + } + + \let\smallexamplefonts\smallfonts + + % Reset fonts + + \globaldefs = 1 + \definetextfontsizexi + \globaldefs = 0 + + \fi % \iftxinativeunicodecapable + +\fi % \ifx\txijapackage\thisisundefined diff --git a/macros/texinfo/texinfo/doc/txi-nb.tex b/macros/texinfo/texinfo/doc/txi-nb.tex new file mode 100644 index 0000000000..b1674062c0 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-nb.tex @@ -0,0 +1,71 @@ +% txi-it.tex -- Norwegian translations for texinfo.tex (1999-10-29, GNU +% Texinfo 4.0). +% +% Copyright (C) 1999, 2007, 2008 Trond Endrest=F8l <endrestol@hotmail.com> +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. + +\txisetlanguage{bokmal}{2}{2} % used for both bokmal and nynorsk + +\plainfrenchspacing + +\gdef\putwordAppendix{Vedlegg} +\gdef\putwordChapter{Kapittel} +\gdef\putwordfile{fil} +\gdef\putwordIndexIsEmpty{(Indeks er tom)} +\gdef\putwordIndexNonexistent{(Indeks eksisterer ikke)} +\gdef\putwordInfo{Info} +\gdef\putwordMethodon{Metode p\aa} +\gdef\putwordNoTitle{Ingen tittel} +\gdef\putwordof{av} +\gdef\putwordon{p\aa} +\gdef\putwordpage{side} +\gdef\putwordsection{avsnitt} +\gdef\putwordSection{Avsnitt} +\gdef\putwordsee{se} +\gdef\putwordSee{Se} +\gdef\putwordShortTOC{Kort innholdsfortegnelse} +\gdef\putwordTOC{Innholdsfortegnelse} +% +\gdef\putwordMJan{januar} +\gdef\putwordMFeb{februar} +\gdef\putwordMMar{mars} +\gdef\putwordMApr{april} +\gdef\putwordMMay{mai} +\gdef\putwordMJun{juni} +\gdef\putwordMJul{juli} +\gdef\putwordMAug{august} +\gdef\putwordMSep{september} +\gdef\putwordMOct{oktober} +\gdef\putwordMNov{november} +\gdef\putwordMDec{desember} +% +\gdef\putwordDefmac{Makro} +\gdef\putwordDefspec{Spesiell form} +\gdef\putwordDefivar{Forekomstvariabel} +\gdef\putwordDefvar{Variabel} +\gdef\putwordDefopt{Brukervalg} +\gdef\putwordDeffunc{Funksjon} +% +% Redefine \today to produce Norwegian +% preferred dates such as 28. januar 1999. +% +\gdef\today{% + \number\day.\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} diff --git a/macros/texinfo/texinfo/doc/txi-nl.tex b/macros/texinfo/texinfo/doc/txi-nl.tex new file mode 100644 index 0000000000..40c4f94ce1 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-nl.tex @@ -0,0 +1,69 @@ +% txi-nl.tex -- Dutch translations for texinfo.tex. +% +% Copyright 1999, 2007, 2008 Free Software Foundation. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. + +\txisetlanguage{dutch}{2}{2} + +\plainfrenchspacing + +\gdef\putwordAppendix{Appendix} +\gdef\putwordChapter{Hoofdstuk} +\gdef\putwordfile{bestand} +\gdef\putwordin{in} +\gdef\putwordIndexIsEmpty{(Index is leeg)} +\gdef\putwordIndexNonexistent{(Index bestaat niet)} +\gdef\putwordInfo{Info} +\gdef\putwordInstanceVariableof{Instantie Variabele van} +\gdef\putwordMethodon{Methode van} +\gdef\putwordNoTitle{Geen titel} +\gdef\putwordof{van} +\gdef\putwordon{op} +\gdef\putwordpage{pagina} +\gdef\putwordsection{sectie} +\gdef\putwordSection{Sectie} +\gdef\putwordsee{zie} +\gdef\putwordSee{Zie} +\gdef\putwordShortTOC{Korte inhoudsopgave} +\gdef\putwordTOC{Inhoudsopgave} +% +\gdef\putwordMJan{Januari} +\gdef\putwordMFeb{Februari} +\gdef\putwordMMar{Maart} +\gdef\putwordMApr{April} +\gdef\putwordMMay{Mei} +\gdef\putwordMJun{Juni} +\gdef\putwordMJul{Juli} +\gdef\putwordMAug{Augustus} +\gdef\putwordMSep{September} +\gdef\putwordMOct{Oktober} +\gdef\putwordMNov{November} +\gdef\putwordMDec{December} +% +\gdef\putwordDefmac{Macro} +\gdef\putwordDefspec{Speciale Vorm} +\gdef\putwordDefvar{Variabele} +\gdef\putwordDefopt{Gebruikers optie} +\gdef\putwordDeffunc{Functie} + +% Produces Day Month Year style of output. +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} diff --git a/macros/texinfo/texinfo/doc/txi-nn.tex b/macros/texinfo/texinfo/doc/txi-nn.tex new file mode 100644 index 0000000000..15185d7688 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-nn.tex @@ -0,0 +1,18 @@ +% No difference between Norwegian Nynorsk and Norwegian bokmal for Texinfo? +% +% Copyright 2008 Free Software Foundation, Inc. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +\input txi-nb diff --git a/macros/texinfo/texinfo/doc/txi-pl.tex b/macros/texinfo/texinfo/doc/txi-pl.tex new file mode 100644 index 0000000000..2b5bc0e153 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-pl.tex @@ -0,0 +1,73 @@ +% txi-pl.tex -- Polish translations for texinfo.tex. +% +% Copyright 2003, 2006, 2007, 2008 Free Software Foundation. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +% Written by Wojciech Polak <polak@gnu.org> on 29-03-2003. +% Modified by Staszek Wawrykiewicz <staw@gust.org.pl> on 01-04-2003. + +\txisetlanguage{polish}{2}{2} + +\plainfrenchspacing + +\gdef\putwordAppendix{Suplement} +\gdef\putwordChapter{Rozdzia} +\gdef\putwordfile{plik} +\gdef\putwordin{w} +\gdef\putwordIndexIsEmpty{(Skorowidz jest pusty)} +\gdef\putwordIndexNonexistent{(Brak skorowidza)} +\gdef\putwordInfo{Info} +\gdef\putwordInstanceVariableof{Przykadowa zmienna} +\gdef\putwordMethodon{Metoda} +\gdef\putwordNoTitle{Brak tytuu} +\gdef\putwordof{z} +\gdef\putwordon{na} +\gdef\putwordpage{strona} +\gdef\putwordsection{cz} +\gdef\putwordSection{Cz} +\gdef\putwordsee{zobacz} +\gdef\putwordSee{Zobacz} +\gdef\putwordShortTOC{Krtka zawarto} +\gdef\putwordTOC{Spis treci} +% +\gdef\putwordMJan{stycznia} +\gdef\putwordMFeb{lutego} +\gdef\putwordMMar{marca} +\gdef\putwordMApr{kwietnia} +\gdef\putwordMMay{maja} +\gdef\putwordMJun{czerwca} +\gdef\putwordMJul{lipca} +\gdef\putwordMAug{sierpnia} +\gdef\putwordMSep{wrzenia} +\gdef\putwordMOct{padziernika} +\gdef\putwordMNov{listopada} +\gdef\putwordMDec{grudnia} +% +\gdef\putwordDefmac{Makro} +\gdef\putwordDefspec{Specjalna forma} +\gdef\putwordDefvar{Zmienna} +\gdef\putwordDefopt{Opcja uytkownika} +\gdef\putwordDeffunc{Funkcja} +% +% Produces Day Month Year style of output. +% +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} diff --git a/macros/texinfo/texinfo/doc/txi-pt.tex b/macros/texinfo/texinfo/doc/txi-pt.tex new file mode 100644 index 0000000000..4c9483c04e --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-pt.tex @@ -0,0 +1,71 @@ +% txi-pt.tex -- Portuguese translations for texinfo.tex. +% +% Copyright 1999, 2007, 2008 Free Software Foundation, Inc. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or (at +% your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +% Written by Lalo Martins <lalo@webcom.com> at 05 August 1999 + +\txisetlanguage{portuguese}{2}{3} + +\plainnonfrenchspacing + +\gdef\putwordAppendix{Ap\^endice} +\gdef\putwordChapter{Cap\'\ptexi tulo} +\gdef\putwordfile{Data} +\gdef\putwordin{em} +\gdef\putwordInfo{Info} +\gdef\putwordMethodon{M\'etodo de} +\gdef\putwordon{em} +\gdef\putwordof{de} +\gdef\putwordpage{P\'agina} +\gdef\putwordsection{se\,c\~ao} +\gdef\putwordSection{Se\,c\~ao} +\gdef\putwordsee{veja} +\gdef\putwordSee{Veja} +\gdef\putwordShortTOC{Breve Sum\'ario} +\gdef\putwordTOC{Sum\'ario} +%% +\gdef\putwordNoTitle{Sem T\'\ptexi tulo} +%% +%% New defintion for the output of months. +\gdef\putwordMJan{Janeiro} +\gdef\putwordMFeb{Fevereiro} +\gdef\putwordMMar{Mar\,co} +\gdef\putwordMApr{Abril} +\gdef\putwordMMai{Maio} +\gdef\putwordMJun{Junho} +\gdef\putwordMJul{Julho} +\gdef\putwordMAug{Agosto} +\gdef\putwordMSep{Setembro} +\gdef\putwordMOct{Outubro} +\gdef\putwordMNov{Novembro} +\gdef\putwordMDec{Dezembro} +%% +%% Index handling should also work correct in german +\gdef\putwordIndexNonexistent{(\'Indice inexistente)} +\gdef\putwordIndexIsEmpty{(\'Indice vazio)} +%% +%% \defmac +\gdef\putwordDefmac{Macro} +%% \defspec +\gdef\putwordDefspec{Forma Especial} +%% \defivar +\gdef\putwordDefivar{Vari\'avel de Inst\^ancia} +%% \defvar +\gdef\putwordDefvar{Vari\'avel} +%% \defopt +\gdef\putwordDefopt{Op\,c\~ao de Usu\'ario} +%% \deffun +\gdef\putwordDeffunc{Fun\,c\~ao} diff --git a/macros/texinfo/texinfo/doc/txi-ru.tex b/macros/texinfo/texinfo/doc/txi-ru.tex new file mode 100644 index 0000000000..c72108e429 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-ru.tex @@ -0,0 +1,72 @@ +% txi-ru.tex -- Russian translations for texinfo.tex. +% +% Copyright 2005, 2007, 2008 Free Software Foundation. +% +% Author: Sergey Poznyakoff +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. + +\txisetlanguage{russian}{2}{2} + +\plainfrenchspacing + +\gdef\putwordAppendix{} +\gdef\putwordChapter{} +\gdef\putwordfile{} +\gdef\putwordin{} +\gdef\putwordIndexIsEmpty{( )} +\gdef\putwordIndexNonexistent{( )} +\gdef\putwordInfo{Info} +\gdef\putwordInstanceVariableof{ } % hmm ?? +\gdef\putwordMethodon{} +\gdef\putwordNoTitle{ } +\gdef\putwordof{} % (??) X Y +\gdef\putwordon{} % ... +\gdef\putwordpage{} +\gdef\putwordsection{} +\gdef\putwordSection{} +\gdef\putwordsee{.} +\gdef\putwordSee{.} +\gdef\putwordShortTOC{ } +\gdef\putwordTOC{} +% +%% (. today) +\gdef\putwordMJan{} +\gdef\putwordMFeb{} +\gdef\putwordMMar{} +\gdef\putwordMApr{} +\gdef\putwordMMay{} +\gdef\putwordMJun{} +\gdef\putwordMJul{} +\gdef\putwordMAug{} +\gdef\putwordMSep{} +\gdef\putwordMOct{} +\gdef\putwordMNov{} +\gdef\putwordMDec{} +% +\gdef\putwordDefmac{} +\gdef\putwordDefspec{ } +\gdef\putwordDefvar{} +\gdef\putwordDefopt{ } +\gdef\putwordDeffunc{} + +% Produces Day Month Year style of output. +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} diff --git a/macros/texinfo/texinfo/doc/txi-sr.tex b/macros/texinfo/texinfo/doc/txi-sr.tex new file mode 100644 index 0000000000..d8baaea709 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-sr.tex @@ -0,0 +1,71 @@ +% txi-src.tex -- Serbian-latin translation for texinfo.tex. +% +% Copyright 2005, 2007, 2008 Free Software Foundation. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +% Created by Predrag Rakic. + +\txisetlanguage{serbian}{2}{2} + +\plainfrenchspacing + +\gdef\putwordAppendix{Prilog} +\gdef\putwordChapter{Glava} +\gdef\putwordfile{datoteka} +\gdef\putwordin{u} +\gdef\putwordIndexIsEmpty{(Indeks je prazan)} +\gdef\putwordIndexNonexistent{(Indeks ne postoji)} +\gdef\putwordInfo{Info} +\gdef\putwordInstanceVariableof{Atribut klase} +\gdef\putwordMethodon{Metod klase} +\gdef\putwordNoTitle{Bez naslova} +\gdef\putwordof{} +\gdef\putwordon{} +\gdef\putwordpage{strana} +\gdef\putwordsection{poglavlje} +\gdef\putwordSection{Poglavlje} +\gdef\putwordsee{vidi} +\gdef\putwordSee{Vidi} +\gdef\putwordShortTOC{Kratak sadr\v{z}aj} +\gdef\putwordTOC{Sadr\v{z}aj} +% +\gdef\putwordMJan{Januar} +\gdef\putwordMFeb{Februar} +\gdef\putwordMMar{Mart} +\gdef\putwordMApr{April} +\gdef\putwordMMay{Maj} +\gdef\putwordMJun{Jun} +\gdef\putwordMJul{Jul} +\gdef\putwordMAug{Avgust} +\gdef\putwordMSep{Septembar} +\gdef\putwordMOct{Oktobar} +\gdef\putwordMNov{Novembar} +\gdef\putwordMDec{Decembar} +% +\gdef\putwordDefmac{Makro} +\gdef\putwordDefspec{Posebna forma} +\gdef\putwordDefvar{Promenljiva} +\gdef\putwordDefopt{Korisni\v{c}ka opcija} +\gdef\putwordDeffunc{Funkcija} + +% Produces Day Month Year style of output. +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} diff --git a/macros/texinfo/texinfo/doc/txi-tr.tex b/macros/texinfo/texinfo/doc/txi-tr.tex new file mode 100644 index 0000000000..f28701fdd2 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-tr.tex @@ -0,0 +1,80 @@ +% txi-tr.tex -- Turkish translations for texinfo.tex. +% +% Copyright 2003, 2007, 2008 Free Software Foundation, Inc. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or (at +% your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +% Written by Alper Ersoy, 5 January 2003, <aersoy@tfz.net> + +\txisetlanguage{turkish}{2}{2} + +\plainfrenchspacing + +\gdef\putwordAppendix{Ek} +\gdef\putwordChapter{Kesim} +\gdef\putwordfile{dosya} +\gdef\putwordInfo{Bilgi} +\gdef\putwordpage{Sayfa} +\gdef\putwordsection{b\"ol\"um} +\gdef\putwordSection{B\"ol\"um} +\gdef\putwordsee{bkz.} +\gdef\putwordSee{Bkz.} +\gdef\putwordShortTOC{\dotaccent{I}\,cindekiler (K\dotless{i}saca)} +\gdef\putwordTOC{\dotaccent{I}\,cindekiler} +%% +%% This one really sucks :\ +\gdef\putwordMethodon{S\dotless{i}n\dotless{i}f:} +%% +%% I could not translate these ones, need examples :\ +%% If anybody out there is using these in turkish, please +%% don't hesitate to send me patches ;) +\gdef\putwordin{in} +\gdef\putwordon{on} +\gdef\putwordof{of} +%% +%% +\gdef\putwordNoTitle{Ba\,sl\dotless{i}s\dotless{i}z} +\gdef\putwordIndexNonexistent{(Dizin bulunmamakta)} +\gdef\putwordIndexIsEmpty{(Dizin bo\,s)} +%% +%% Months +\gdef\putwordMJan{Ocak} +\gdef\putwordMFeb{\,Subat} +\gdef\putwordMMar{Mart} +\gdef\putwordMApr{Nisan} +\gdef\putwordMMai{May\dotless{i}s} +\gdef\putwordMJun{Haziran} +\gdef\putwordMJul{Temmuz} +\gdef\putwordMAug{A\u{g}ustos} +\gdef\putwordMSep{Eyl\"ul} +\gdef\putwordMOct{Ekim} +\gdef\putwordMNov{Kas\dotless{i}m} +\gdef\putwordMDec{Aral\dotless{i}k} +%% +%% Definitions +\gdef\putwordDefmac{Makro} +\gdef\putwordDefspec{\"Ozel Yap\dotless{i}} +\gdef\putwordDefopt{Se\,cenek} +\gdef\putwordDefvar{De\u{g}i\,sken} +\gdef\putwordDeffunc{Fonksiyon} +%% +% Produces Day Month Year style of output. +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} diff --git a/macros/texinfo/texinfo/doc/txi-uk.tex b/macros/texinfo/texinfo/doc/txi-uk.tex new file mode 100644 index 0000000000..8d71d8bba1 --- /dev/null +++ b/macros/texinfo/texinfo/doc/txi-uk.tex @@ -0,0 +1,71 @@ +% txi-uk.tex -- Ukrainian translations for texinfo.tex. +% +% Copyright 2005, 2007, 2008 Free Software Foundation. +% +% Author: Sergey Poznyakoff +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. + +\txisetlanguage{ukrainian}{2}{2} + +\plainfrenchspacing + +\gdef\putwordAppendix{} +\gdef\putwordChapter{Ħ} +\gdef\putwordfile{} +\gdef\putwordin{} +\gdef\putwordIndexIsEmpty{( )} +\gdef\putwordIndexNonexistent{( դ)} +\gdef\putwordInfo{ Info} +\gdef\putwordInstanceVariableof{ͦ } +\gdef\putwordMethodon{ } +\gdef\putwordNoTitle{ } +\gdef\putwordof{} % ?? +\gdef\putwordon{} % æ ... +\gdef\putwordpage{Ҧ} +\gdef\putwordsection{} +\gdef\putwordSection{} +\gdef\putwordsee{.} +\gdef\putwordSee{.} +\gdef\putwordShortTOC{ ͦ} +\gdef\putwordTOC{ͦ} +% +\gdef\putwordMJan{Ӧ} +\gdef\putwordMFeb{} +\gdef\putwordMMar{} +\gdef\putwordMApr{צ} +\gdef\putwordMMay{} +\gdef\putwordMJun{} +\gdef\putwordMJul{} +\gdef\putwordMAug{} +\gdef\putwordMSep{} +\gdef\putwordMOct{} +\gdef\putwordMNov{} +\gdef\putwordMDec{} +% +\gdef\putwordDefmac{} +\gdef\putwordDefspec{æ } +\gdef\putwordDefvar{ͦ} +\gdef\putwordDefopt{æ } +\gdef\putwordDeffunc{æ} + +% Produces Day Month Year style of output. +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} diff --git a/macros/texinfo/texinfo/doc/version-stnd.texi b/macros/texinfo/texinfo/doc/version-stnd.texi new file mode 100644 index 0000000000..bd8d35fb8b --- /dev/null +++ b/macros/texinfo/texinfo/doc/version-stnd.texi @@ -0,0 +1,4 @@ +@set UPDATED 16 February 2019 +@set UPDATED-MONTH February 2019 +@set EDITION 6.6 +@set VERSION 6.6 diff --git a/macros/texinfo/texinfo/doc/version.texi b/macros/texinfo/texinfo/doc/version.texi new file mode 100644 index 0000000000..bd8d35fb8b --- /dev/null +++ b/macros/texinfo/texinfo/doc/version.texi @@ -0,0 +1,4 @@ +@set UPDATED 16 February 2019 +@set UPDATED-MONTH February 2019 +@set EDITION 6.6 +@set VERSION 6.6 |